eslint-plugin-structure-prettifier

ESLint plugin for enforcing consistent structures formatting across JavaScript/TypeScript code. This plugin automatically formats arrays, objects, imports, exports, and destructuring patterns based on configurable rules.

Features

• 📋 Arrays - Format array literals and destructuring with hole support
• 📦 Objects - Format object literals and destructuring with context-aware length calculation
• 📥 Imports - Consistent formatting including mixed default+named imports
• 📤 Exports - Consistent formatting for export statements
• 🔧 Auto-fix - Intelligent formatting with proper indentation
• ⚙️ Configurable - Flexible options for different coding styles
• 🚀 Fast - Unified architecture with optimized AST traversal

Why?

It was September, 2025, and we still don't have a unified ESLint plugin that handles structure formatting consistently across ArrayExpression, ObjectExpression, ImportDeclaration, ExportNamedDeclaration, and friends. Instead, we have a fragmented ecosystem where each structure type gets its own special treatment (or no treatment at all), leading to inconsistent codebases where your imports look pristine but your object destructuring looks like it survived a formatting apocalypse.

Maybe I'm wrong, but here's the kicker: ESLint already handles many of the formatting features that Prettier provides. Semicolons? Check. Quotes? Check. Spacing? Check. The missing piece? Intelligent structure formatting decisions. This plugin fills that gap, giving you the power to ditch Prettier entirely while maintaining consistent, configurable formatting across all JavaScript/TypeScript structures. No more tool conflicts, no more configuration headaches — just pure ESLint-powered formatting that actually understands your code's context.

Installation

npm i eslint-plugin-structure-prettifier -D

yarn add eslint-plugin-structure-prettifier -D

pnpm add eslint-plugin-structure-prettifier -D

bun add eslint-plugin-structure-prettifier -D

Usage

ESLint flat config (ESLint 9+)

// eslint.config.js
import { defineConfig } from 'eslint'
import pluginStructurePrettifier from 'eslint-plugin-structure-prettifier'

export default defineConfig(
  {
    plugins: {
        'structure-prettifier': pluginStructurePrettifier
    },
    rules: {
      'structure-prettifier/enforce': 'error'
    },
  },
)

Legacy ESLint config

{
  "plugins": ["structure-prettifier"],
  "rules": {
    "structure-prettifier/enforce": "error"
  }
}

Predefined configurations

recommended

Balanced settings suitable for most projects:

• maxLineLength: 120
• minItems: Number.POSITIVE_INFINITY
• All ignore* options: false (everything checked)

import multiline from 'eslint-plugin-structure-prettifier'

export default defineConfig(
    // other configs...
    multiline.configs.recommended,
)

In legacy ESLint config just add:

{
  "extends": ["plugin:structure-prettifier/recommended"]
}

strict

Stricter formatting for consistent codebases:

• maxLineLength: 80
• minItems: 3
• All ignore* options: false (everything checked)

// Strict (more formatting)
export default defineConfig(
    // other configs...
    multiline.configs.strict,
)

In legacy ESLint config just add:

{
  "extends": ["plugin:structure-prettifier/strict"]
}

One rule

structure-prettifier/enforce

Enforces consistent structure formatting for arrays, objects, imports, exports, and destructuring patterns.

Options

| Option | Type | Default | Description | |---------------------------|------|----------------------------|----------------------------------------------------------------------------| | maxLineLength | number | 120 | Maximum line length before enforcing newlines | | minItems | number | Number.POSITIVE_INFINITY | Minimum number of properties/specifiers to enforce newlines | | ignoreArrayExpression | boolean | false | Whether to ignore array expressions (array creation) | | ignoreArrayPattern | boolean | false | Whether to ignore array patterns (array destructuring) | | ignoreCallExpression | boolean | false | Whether to ignore objects used as function arguments | | ignoreDynamicImport | boolean | false | Whether to ignore dynamic import destructuring (await import()) | | ignoreExportDeclaration | boolean | false | Whether to ignore export declarations | | ignoreImportDeclaration | boolean | false | Whether to ignore import declarations | | ignoreObjectExpression | boolean | false | Whether to ignore object expressions (object creation) | | ignoreObjectPattern | boolean | false | Whether to ignore object patterns (object destructuring) | | ignoreRequire | boolean | false | Whether to ignore require destructuring (const { } = require()) |

When the rule triggers

The structure-prettifier/enforce rule will enforce newlines following these strict priorities:

🥇 Priority 1: Line length (always enforced)

• Line too long: When single-line representation exceeds maxLineLength
• Context-aware: For function call arguments, considers entire call expression length
• Smart calculation: Excludes all comment types (JSDoc, inline, block) from length
• Override: No ignore* option can override this priority

🥈 Priority 2: Property count

• Too many properties: When count reaches minItems threshold
• Special case: minItems: Number.POSITIVE_INFINITY means never format by count alone

Node type filtering

Before any priority checks, these ignore* options can completely skip processing:

• ignoreArrayExpression: true → Skip array creation [elem1, elem2]
• ignoreArrayPattern: true → Skip array destructuring [elem1, elem2] = arr
• ignoreCallExpression: true → Skip arrays/objects in function calls
• ignoreDynamicImport: true → Skip const { } = await import()
• ignoreExportDeclaration: true → Skip export { } from
• ignoreImportDeclaration: true → Skip import { } from
• ignoreObjectExpression: true → Skip object creation { key: value }
• ignoreObjectPattern: true → Skip object destructuring { key } = obj
• ignoreRequire: true → Skip const { } = require()

[!NOTE] ️Important: All options use ignore* pattern (inverted logic):

• ignore*: false (default) = Enable checking for this type
• ignore*: true = Disable checking for this type

This means by default, everything is checked and formatted according to priorities.

Quick Reference: Node Types

| Code Pattern | Node Type | Ignore Option | |----------------------------------------|---------------------|---------------------------| | [elem1, elem2] | ArrayExpression | ignoreArrayExpression | | [elem1, elem2] = arr | ArrayPattern | ignoreArrayPattern | | { key: value } | ObjectExpression | ignoreObjectExpression | | { key } = obj | ObjectPattern | ignoreObjectPattern | | import { a, b } from 'mod' | ImportDeclaration | ignoreImportDeclaration | | export { a, b } from 'mod' | ExportDeclaration | ignoreExportDeclaration | | const { a, b } = require('mod') | VariableDeclaration | ignoreRequire | | const { a, b } = await import('mod') | VariableDeclaration | ignoreDynamicImport | | func({ a, b }) | ObjectExpression | ignoreCallExpression | | func([elem1, elem2]) | ArrayExpression | ignoreCallExpression |

Special Cases

• Empty structures: {}, [] never get formatted
• Array holes: [1, , 3] handled without errors, holes preserved
• Mixed imports: import default, { named } - only named imports checked for consistency
• Function call context: Line length includes entire call expression
• Comment exclusion: JSDoc /** */, block /* */, inline // excluded from length

Examples

❌ Incorrect

// Too many properties (>= minItems: 3)
const config = { host: 'localhost', port: 3000, ssl: true };

// Line too long (exceeds maxLineLength)
const data = { veryLongPropertyName: 'value', anotherVeryLongPropertyName: 'value' };

// Line too long (exceeds maxLineLength)
const settings = { veryLongPropertyName: 'very long value that exceeds maxLineLength', another: 'value' };

// Mixed formatting (inconsistent)
const mixed = { a: 1, b: 2,
  c: 3,
  d: 4 };

// Multiple imports on one line (>= minItems)
import { ComponentA, ComponentB, ComponentC, ComponentD } from 'components';

// Multiple exports on one line  
export { functionA, functionB, functionC, functionD } from 'utils';

// Object pattern destructuring
const { name, email, address, phone } = user;

// Long line in function call context
const result = Object.entries({ veryLongProp: 1, anotherLongProp: 2 }).map(x => x);

// Array with holes (inconsistent)
const [a, b, ,
    c, d] = array;

✅ Correct

// Properly formatted with newlines
const config = {
  host: 'localhost',
  port: 3000,
  ssl: true
};

// Properly formatted with newlines
const data = {
  veryLongPropertyName: 'value',
  anotherVeryLongPropertyName: 'value'
};

// Long lines properly formatted
const settings = {
  veryLongPropertyName: 'very long value that exceeds maxLineLength',
  another: 'value'
};

// Consistent formatting
const mixed = {
  a: 1,
  b: 2,
  c: 3,
  d: 4
};

// Import destructuring with newlines
import {
  ComponentA,
  ComponentB,
  ComponentC,
  ComponentD
} from 'components';

// Export destructuring with newlines
export {
  functionA,
  functionB,
  functionC,
  functionD
} from 'utils';

// Object pattern destructuring
const {
  name,
  email,
  address,
  phone
} = user;

// Short objects can stay on one line (< minItems)
const short = { a: 1, b: 2 };

// Context-aware formatting in function calls
const result = Object.entries({
  veryLongProp: 1,
  anotherLongProp: 2
}).map(x => x);

// Array with holes (consistent)
const [a, b, , c, d] = array;

// Mixed imports (default + named)
import defaultExport, {
  namedExport1,
  namedExport2
} from 'module';

Auto-fixing

This rule provides comprehensive automatic fixing:

• ✅ Adds newlines after opening braces/brackets
• ✅ Places each property/specifier on a separate line
• ✅ Adds proper indentation based on context
• ✅ Adds newlines before closing braces/brackets
• ✅ Preserves comments and existing formatting where appropriate
• ✅ Handles edge cases - Array holes, spread operators, mixed imports
• ✅ Context-aware indentation - Proper formatting for function call arguments

Integration with other tools

ESLint-only approach

This plugin enables a Prettier-free workflow by handling the last missing piece - structure formatting. Combined with existing ESLint rules, you get complete formatting control:

// This plugin: structure decisions (when to break lines)
const config = {
  host: 'localhost',
  port: 3000
};

// Other ESLint rules: quotes, semicolons, spacing, etc.

TypeScript

Full TypeScript support - works with .ts, .tsx files and TypeScript-specific syntax.

Known conflicts

This plugin may conflict with:

• array-element-newline (ESLint core)
• object-curly-newline (ESLint core)
• object-property-newline (ESLint core)
• @stylistic/object-* rules
• @stylistic/array-element-newline rule
• Prettier (structure formatting overlap)

Recommendation: Disable conflicting rules when using this plugin. For Prettier-free setup, this plugin replaces Prettier's structure formatting entirely.

Troubleshooting

Option not working

1. Verify ESLint configuration is loading correctly
2. Clear any ESLint cache: eslint --cache-file .eslintcache

Performance with large files

• Consider reducing maxLineLength for faster processing
• Use file-specific overrides for selective formatting
• The plugin handles deeply nested structures safely

License

MIT License - see the LICENSE file for details.