sort-imports

Enforce sorted imports.

Maintaining a consistent and sorted order of imports is crucial for improving code readability and organization.

This rule ensures that imports are easily locatable and quickly scannable, especially in modules with numerous import statements.

By reducing the likelihood of errors caused by import conflicts and providing a clear structure, this rule helps developers manage imports efficiently and maintain a tidy codebase.

Important

If you use the sort-imports rule or the order rule from the eslint-plugin-import plugin, it is highly recommended to disable them to avoid conflicts.

If you use the prettier-plugin-sort-imports plugin, remove them from the prettier config to avoid conflicts.

Rule perfectionist/sort-imports works in a similar way to rule import/order, but with some differences:

Supporting for new import types:

'side-effect'
'style'
'builtin-type'
'internal-type'
'parent-type'
'sibling-type'
'index-type'

Supporting for adding custom import groups
Sorting not only alphabetically, but also naturally and by line length

Try it out

Options

This rule accepts an options object with the following properties:

type

_{default: 'alphabetical'}

Specifies the sorting method.

'alphabetical' — Sort items alphabetically (e.g., “a” < “b” < “c”).
'natural' — Sort items in a natural order (e.g., “item2” < “item10”).
'line-length' — Sort items by the length of the code line (shorter lines first).

order

_{default: 'asc'}

Determines whether the sorted items should be in ascending or descending order.

'asc' — Sort items in ascending order (A to Z, 1 to 9).
'desc' — Sort items in descending order (Z to A, 9 to 1).

ignoreCase

_{default: true}

Controls whether sorting should be case-sensitive or not.

true — Ignore case when sorting alphabetically or naturally (e.g., “A” and “a” are the same).
false — Consider case when sorting (e.g., “A” comes before “a”).

internalPattern

_{default: ['~/**']}

Allows you to specify a pattern for identifying internal imports. This is useful for distinguishing your own modules from external dependencies.

You can use glob patterns to define these internal imports.

sortSideEffects

_{default: false}

Specifies whether side effect imports should be sorted. By default, sorting side-effect imports is disabled for security reasons.

true — Sort side effect imports.
false — Do not sort side effect imports.

newlinesBetween

_{default: 'always'}

Specifies how new lines should be handled between import groups.

ignore — Do not report errors related to new lines between import groups.
always — Enforce one new line between each group, and forbid new lines inside a group.
never — No new lines are allowed in the entire import section.

maxLineLength

_{default: undefined}

Specifies a maximum line length for sorting imports. When the line length exceeds this number, sorting will be based only on the import name, excluding the elements.

This option is only available when the type is set to 'line-length'.

groups

_{default:
[
'type',
['builtin', 'external'],
'internal-type',
'internal',
['parent-type', 'sibling-type', 'index-type'],
['parent', 'sibling', 'index'],
'object',
'unknown',
]}

Allows you to set up a list of import groups for sorting. Groups help organize imports into meaningful categories, making your code more readable and maintainable. Multiple groups can be combined.

There are a lot of predefined groups.

Predefined Groups:

'builtin' — Node.js Built-in Modules.
'external' — External modules installed in the project.
'internal' — Your internal modules.
'parent' — Modules from the parent directory.
'sibling' — Modules from the same directory.
'side-effect' — Side effect imports.
'side-effect-style' — Side effect style imports.
'index' — Main file from the current directory.
'object' — TypeScript object imports.
'style' — Styles.
'external-type' — TypeScript type imports from external modules.
'builtin-type' — TypeScript type imports from built-in modules.
'internal-type' — TypeScript type imports from your internal modules.
'parent-type' — TypeScript type imports from the parent directory.
'sibling-type' — TypeScript type imports from the same directory.
'index-type' — TypeScript type imports from the main directory file.
'unknown' — Imports that don’t fit into any other group.

Example:

// 'builtin' - Node.js Built-in Modules
import path from 'path'
// 'external' - External modules installed in the project
import axios from 'axios'
// 'internal' - Your internal modules
import Button from '~/components/Button'
// 'parent' - Modules from parent directory
import formatNumber from '../utils/format-number'
// 'sibling' - Modules from the same directory
import config from './config'
// 'side-effect' - Side effect imports
import './set-production-env.js'
// side-effect-style - Side effect style imports
import './styles.scss'
// 'index' - Main file from the current directory
import main from '.'
// 'object' - TypeScript object-imports
import log = console.log
// 'style' - Styles
import styles from './index.module.css'
// 'external-type' - TypeScript type imports
import type { FC } from 'react'
// 'builtin-type' - TypeScript type imports from Built-in Modules
import type { Server } from 'http'
// 'internal-type' - TypeScript type imports from your internal modules
import type { User } from '~/users'
// 'parent-type' - TypeScript type imports from parent directory
import type { InputProps } from '../Input'
// 'sibling-type' - TypeScript type imports from the same directory
import type { Details } from './data'
// 'index-type' - TypeScript type imports from main directory file
import type { BaseOptions } from './index.d.ts'

customGroups

_{default: { value: {}, type: {} }}

You can define your own groups for importing values of types using custom glob patterns for matching.

Example:

   groups: [
+    'react',
     'type',
     ['builtin', 'external'],
+    'lodash',
     'internal-type',
     'internal',
     ['parent-type', 'sibling-type', 'index-type'],
     ['parent', 'sibling', 'index'],
     'object',
     'unknown',
   ],
+  customGroups: {                  
+    value: {                       
+     react: ['react', 'react-*'],
+     lodash: 'lodash',
+    },
+    type: {                        
+      react: ['react', 'react-*'],
+    }                              
+  },
 }

environment

_{default: 'node'}

Specifies which environment’s built-in modules should be recognized. If you are using Bun, change the value to 'bun'.

Usage

Version

This rule was introduced in v0.9.0.