ESLint Plugin Perfectionist

5.9.0 verified Sat Apr 25 auth: no javascript

An ESLint plugin that enforces sorting of various data structures including objects, imports, TypeScript types, enums, JSX props, Svelte attributes, and more. Current stable version is 5.9.0 with frequent releases (multiple per month). Supports ESLint v8.45+, v9, and v10. All rules are auto-fixable. Key differentiators: supports multiple sort orders (alphabetical, natural, line-length), highly configurable with group/partition/selector options, and covers broader range of structures than alternatives like eslint-plugin-simple-import-sort or eslint-plugin-import.

Common errors

error Error: Failed to load plugin 'perfectionist' declared in 'plugins': Cannot find module 'eslint-plugin-perfectionist' ↓

cause Missing npm install or incorrect import path in flat config.

fix

Run 'npm install --save-dev eslint-plugin-perfectionist' and ensure import uses correct name.

error TypeError: Cannot read properties of undefined (reading 'sort-imports') ↓

cause Using string rule name without registering plugin object in flat config.

fix

Add 'plugins: { perfectionist }' to the flat config object.

error Configuration for rule 'perfectionist/sort-imports' is invalid: Unknown option 'type' ↓

cause Using option 'type' in legacy config where it may not be recognized.

fix

Update to flat config or use correct options for your version; check documentation.

error Error: Requires ESLint >=8.45.0 ↓

cause Installed ESLint version is too old.

fix

Upgrade ESLint to v8.45.0 or higher (v9/v10 also supported).

error Cannot find module 'eslint-plugin-perfectionist' or its corresponding type declarations. ↓

cause Missing TypeScript type declarations; the package ships types, but IDE may not pick them up.

fix

Ensure 'eslint-plugin-perfectionist' is installed and tsconfig.json includes 'node_modules' in 'types' or uses 'skipLibCheck'.

Warnings

breaking v3 dropped support for ESLint < 8 and CJS configuration. ↓

fix Upgrade to ESLint v8+ and migrate to flat config (eslint.config.js).

breaking v5 requires Node.js >=20.0.0 or >=22.0.0. ↓

fix Update Node.js to version 20.x or 22.x.

gotcha The 'sort-imports' rule does not automatically group side-effect imports; they must be explicitly in a 'side-effect' group. ↓

fix Include 'side-effect' in the 'groups' array if you want side-effect imports sorted separately.

gotcha Some rules may conflict with Prettier or other formatters when sorting by line-length. ↓

fix Use 'alphabetical' type or disable conflicting formatting rules.

deprecated The legacy .eslintrc format is deprecated; flat config is recommended. ↓

fix Switch to eslint.config.js flat config.

Install

npm install eslint-plugin-perfectionist

yarn add eslint-plugin-perfectionist

pnpm add eslint-plugin-perfectionist

Imports

default export (plugin object)
wrong
```
const perfectionist = require('eslint-plugin-perfectionist')
```
correct
```
import perfectionist from 'eslint-plugin-perfectionist'
```
Plugin is ESM-only since v3. Use import in flat config; require() will not work in CJS projects.

sort-imports rule

wrong

module.exports = { rules: { 'perfectionist/sort-imports': 'error' } }

correct

import perfectionist from 'eslint-plugin-perfectionist'; export default [ { plugins: { perfectionist }, rules: { 'perfectionist/sort-imports': 'error' } } ]

Flat config requires the plugin object in 'plugins' key. Legacy .eslintrc format is deprecated in favor of flat config.

configs (recommended)

wrong

module.exports = { extends: ['plugin:perfectionist/recommended-alphabetical'] }

correct

import perfectionist from 'eslint-plugin-perfectionist'; export default [...perfectionist.configs['recommended-alphabetical']]

Configs are exported as arrays for flat config. Legacy 'extends' string works only with old ESLint config format.

sort-objects rule

import perfectionist from 'eslint-plugin-perfectionist'; export default [ { plugins: { perfectionist }, rules: { 'perfectionist/sort-objects': ['error', { type: 'alphabetical' }] } } ]

Each rule accepts options like 'type' (alphabetical, line-length, natural) and custom groups.

Quickstart

Shows flat config setup with recommended alphabetical config and custom sort-imports rule options.

// eslint.config.js
import js from '@eslint/js';
import perfectionist from 'eslint-plugin-perfectionist';

export default [
  js.configs.recommended,
  ...perfectionist.configs['recommended-alphabetical'],
  {
    rules: {
      'perfectionist/sort-imports': ['error', {
        type: 'alphabetical',
        order: 'asc',
        ignoreCase: true,
        newlinesBetween: 'ignore',
        groups: [
          'type',
          'internal',
          'external',
          'builtin',
          'parent',
          'sibling',
          'index',
          'object',
          'style',
          'side-effect',
          'unknown',
        ],
        customGroups: { value: {}, type: {} },
      }],
    },
  },
];