eslint-plugin-simple-import-sort

Sorting is generally safe, but there are specific edge cases to consider:

Side Effect Imports

Imports that only run side effects (e.g., import "some-polyfill";) are not sorted; they stay in their original input order to prevent breaking code that relies on execution order.

Re-exports and Name Collisions

When re-exporting items (e.g., export * from "./one.js";), the plugin's sorting is safe in most environments (Node.js, Browsers, Webpack, Parcel, TypeScript) because they handle duplicate names via errors or by prioritizing the first declaration. However, Rollup may issue a warning and use the first declaration, which could theoretically be unsafe if you rely on a specific re-export order for name resolution.

Best Practices

• Avoid relying on side effects from re-exports.
• If you have an import that both exports items and runs side effects, try to refactor it to separate those concerns.

The plugin handles exports differently than imports:

Grouping

Unlike imports, there is no automatic grouping for exports. Grouping is performed manually using comments on their own line. A comment starts a new group, while comments on the same line as an export or within a block comment do not.

Sorting

• Re-exports: Sequences of re-exports (e.g., export * from "x") are sorted.
• Other Exports: Other types of exports (e.g., export const x = 1) are not reordered relative to other export statements, but the items inside the braces are sorted.
• Internal Item Sorting:
  • Imports: import { a as b } is sorted by the local name a (the "stable" name).
  • Exports: export { b as a } is sorted by the external name a (the interface name).
  • Types: import type and export type are sorted as if the type keyword were not there.

Example of Manual Grouping

export * from "x";
export * from "y";

// This comment starts a new group.
export * from "a";

/* This comment does not. */ export * from "b";

/* But this does. */
export * from "./";

// This comment groups some more exports:
export { e } from "../..";
export { f } from "../Utils";
export { g } from ".";
export { h } from "./constants";
export { i } from "./styles";

// Other exports – the plugin does not touch these, other than sorting named
// exports inside braces.
export var one = 1;
export let two = 2;
export const three = 3;
export function func() {}
export class Class {}
export type Type = string;
export { named, other as renamed };
export type { T, U as V };
export default whatever;

The plugin sorts imports by first identifying "chunks" (sequences of imports separated only by whitespace/comments) and then grouping them into sections separated by blank lines.

Default Import Grouping Order

1. Side effect imports: e.g., import "./setup" (not sorted internally).
2. Node.js builtins: prefixed with node:, e.g., import * as fs from "node:fs".
3. Packages: npm packages and Node.js builtins without node:, e.g., import react from "react".
4. Absolute/Alias imports: e.g., import a from "/a" or import a from "@/foo".
5. Relative imports: e.g., import a from "./a".

Sorting Rules within Groups

• Alphabetical: Sorted by the from string, case-insensitively, using Intl.Collator (numeric sorting enabled).
• Directory Structure: For relative imports, higher-level directories come first: "../../utils" < "../utils" < ".".
• Type Imports: If both import type and regular imports exist for the same source, import type comes first.
• Import Styles: For the same source, the order is:
  1. Namespace imports (import * as X from "y")
  2. Default imports (import X from "y")
  3. Named imports (import { X } from "y")

Note: Use eslint --fix or an ESLint editor extension to apply these changes automatically. Do not attempt to fix them manually.

When sorting imports or exports, the plugin moves associated comments along with the items.

Comment Rules

• Comments placed above, at the start, or at the end of an import/export line move with that item.
• Important: Comments located above the entire first import/export chunk or below the entire last chunk are never moved by the plugin. You must move these manually if they need to be repositioned.
• Comments inside curly braces (e.g., import { /* comment */ a } from '...') are also moved with the items.

Whitespace Rules

• Blank Lines: The plugin removes all blank lines within a chunk of imports/exports, except for those inside /**/ comments and the blank lines it automatically adds between groups defined in your configuration.
• One per line: The plugin enforces exactly one import or export per line.
• Odd Spacing: Because the plugin re-uses existing whitespace to maintain compatibility with other ESLint rules, the autofix might occasionally produce slightly unusual spacing (e.g., missing spaces after commas). It is recommended to use Prettier or other ESLint whitespace rules to clean this up.