Skip to content

Latest commit

 

History

History
694 lines (525 loc) · 27.1 KB

README.md

File metadata and controls

694 lines (525 loc) · 27.1 KB
Raw

eslint-plugin-simple-import-sort

Easy autofixable import sorting.

This is for those who use eslint --fix (autofix) a lot and want to completely forget about sorting imports!

Example

import React from "react";
import Button from "../Button";

import styles from "./styles.css";
import type { User } from "../../types";
import { getUser } from "../../api";

import PropTypes from "prop-types";
import classnames from "classnames";
import { truncate, formatNumber } from "../../utils";

⬇️

import classnames from "classnames";
import PropTypes from "prop-types";
import React from "react";

import { getUser } from "../../api";
import type { User } from "../../types";
import { formatNumber, truncate } from "../../utils";
import Button from "../Button";
import styles from "./styles.css";

More examples

Installation

npm install --save-dev eslint-plugin-simple-import-sort

ℹ️ This is an ESLint plugin. 👉 Getting Started with ESLint

Usage

Add "simple-import-sort" to "plugins" in your .eslintrc:

{
  "plugins": ["simple-import-sort"]
}

Then add the rules for sorting imports and exports:

{
  "rules": {
    "simple-import-sort/imports": "error",
    "simple-import-sort/exports": "error"
  }
}

Make sure not to use other sorting rules at the same time:

ℹ️ Note: There used to be a rule called "simple-import-sort/sort". Since version 6.0.0 it’s called "simple-import-sort/imports".

Example configuration

This example uses eslint-plugin-import, which is optional.

It is recommended to also set up Prettier, to help formatting your imports (and all other code) nicely.

{
  "parserOptions": {
    "sourceType": "module"
  },
  "env": { "es6": true },
  "plugins": ["simple-import-sort", "import"],
  "rules": {
    "simple-import-sort/imports": "error",
    "simple-import-sort/exports": "error",
    "import/first": "error",
    "import/newline-after-import": "error",
    "import/no-duplicates": "error"
  },
  "overrides": [
    {
      "files": "server/**/*.js",
      "env": { "node": true },
      "rules": {
        "simple-import-sort/imports": "off",
        "import/order": ["error", { "newlines-between": "always" }]
      }
    }
  ]
}
  • "sourceType": "module" is needed so ESLint doesn’t report import and export as syntax errors.
  • simple-import-sort/imports and simple-import-sort/exports are turned on for all files.
  • import/first makes sure all imports are at the top of the file. (autofixable)
  • import/newline-after-import makes sure there’s a newline after the imports. (autofixable)
  • import/no-duplicates merges import statements of the same file. (autofixable, mostly)
  • For Node.js code, simple-import-sort/imports is turned off and replaced with import/order for sorting of require calls.

With the above configuration, you don’t need to scroll to the top of the file to add another import. Just put it above your function! ESLint will then snap it into place (at the top of the file, in order, and without duplicates).

Sort order

This plugin is supposed to be used with autofix, ideally directly in your editor via an ESLint extension, or with eslint --fix otherwise.

This section is for learning how the sorting works, not for how to manually fix errors. Use autofix!

TL;DR: First group, then sort alphabetically.

Grouping

imports

First, the plugin finds all chunks of imports. A “chunk” is a sequence of import statements with only comments and whitespace between. Each chunk is sorted separately. Use import/first if you want to make sure that all imports end up in the same chunk.

Then, each chunk is grouped into sections with a blank line between each.

  1. import "./setup": Side effect imports. (These are not sorted internally.)
  2. import react from "react": Packages (npm packages and Node.js builtins).
  3. import a from "/a": Absolute imports and other imports such as Vue-style @/foo.
  4. import a from "./a": Relative imports.

Note: The above groups are very loosely defined. See Custom grouping for more information.

exports

Sequences of re-exports (exports with from) are sorted. Other types of exports are not reordered.

Unlike imports, there’s no automatic grouping of exports. Instead a comment on its own line starts a group. This leaves the grouping up to you to do manually.

The following example has 3 groups (one with “x” and “y”, one with “a” and “b” and one with “./”):

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

// This comment starts a new group.
/* This one does not. */ export * from "a"; // Neither does this one.
/* Nor this
one */ export * from "b";
/* But this one does. */
export * from "./";

Each group is sorted separately, and the groups themselves aren’t sorted – they stay where you wrote them.

Without the grouping comments the above example would end up like this:

export * from "./";
/* This one does not. */ export * from "a"; // Neither does this one.
/* Nor this
one */ export * from "b";
export * from "x";
export * from "y";

Sorting

Within each section, the imports/exports are sorted alphabetically on the from string (see also “Why sort on from?”). Keep it simple! It helps looking at the code here:

const collator = new Intl.Collator("en", {
  sensitivity: "base",
  numeric: true,
});

function compare(a, b) {
  return collator.compare(a, b) || (a < b ? -1 : a > b ? 1 : 0);
}

In other words, the imports/exports within groups are sorted alphabetically, case-insensitively and treating numbers like a human would, falling back to good old character code sorting in case of ties. See Intl.Collator for more information.

There’s one addition to the alphabetical rule: Directory structure. Relative imports/exports of files higher up in the directory structure come before closer ones – "../../utils" comes before "../utils", which comes before ".". (In short, . and / sort before any other (non-whitespace, non-control) character. ".." and similar sort like "../," (to avoid the “shorter prefix comes first” sorting concept).)

If both import type and regular imports are used for the same source, the type imports come first. Same thing for export type. (You can move type imports to their own group, as mentioned in custom grouping.)

Example

// Side effect imports. (These are not sorted internally.)
import "./setup";
import "some-polyfill";
import "./global.css";

// Packages.
import type A from "an-npm-package";
import a from "an-npm-package";
import fs from "fs";
import b from "https://example.com/script.js";

// Absolute imports and other imports.
import c from "/";
import d from "/home/user/foo";
import Error from "@/components/error.vue";

// Relative imports.
import e from "../..";
import type { B } from "../types";
import typeof C from "../types";
import f from "../Utils"; // Case insensitive.
import g from ".";
import h from "./constants";
import i from "./styles";

// Different types of exports:
export { a } from "../..";
export { b } from "/";
export { Error } from "@/components/error.vue";
export * from "an-npm-package";
export { readFile } from "fs";
export * as ns from "https://example.com/script.js";

// 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;

Regardless of group, imported items are sorted like this:

import {
  // First, type imports. (`export { type x, typeof y }` is a syntax error).
  type x,
  typeof y,
  // Numbers are sorted by their numeric value:
  img1,
  img2,
  img10,
  // Then everything else, alphabetically:
  k,
  L, // Case insensitive.
  m as anotherName, // Sorted by the “external interface” name “m”, not “anotherName”.
  m as tie, // But do use the file-local name in case of a tie.
  n,
} from "./x";

Exported items are sorted even for exports without from (even though the whole export statement itself isn’t sorted in relation to other exports):

export {
  k,
  L, // Case insensitive.
  anotherName as m, // Sorted by the “external interface” name “m”, not “anotherName”.
  // tie as m, // For exports there can’t be ties – all exports must be unique.
  n,
};
export type { A, B, A as C };

At first it might sound counter-intuitive that a as b is sorted by a for imports, but by b for exports. The reason for doing it this way is to pick the most “stable” name. In import { a as b } from "./some-file.js", the as b part is there to avoid a name collision in the file without having to change some-file.js. In export { b as a }, the b as part is there to avoid a name collision in the file without having to change the exported interface of the file.

Custom grouping

For a long time, this plugin used to have no options, which helped keeping it simple.

While the human alphabetical sorting and comment handling seems to work for a lot of people, grouping of imports is more difficult. Projects differ too much to have a one-size-fits-all grouping. (Note, for exports the grouping is manual using comments – see exports).

However, the default grouping is fine for many use cases! Don’t bother learning how custom grouping works unless you really need it.

If you’re looking at custom grouping because you want to move src/Button, @company/Button and similar – also consider using names that do not look like npm packages, such as @/Button and ~company/Button. Then you won’t need to customize the grouping at all, and as a bonus things might be less confusing for other people working on the code base.

In the future, it would be cool if the plugin could automatically detect your “first party”/“absolute” imports for TypeScript projects by reading your tsconfig.json – see issue #31.

There is one option (and I would really like it to stay that way!) called groups that allows you to:

  • Move src/Button, @company/Button and similar out of the (third party) “packages” group, into their own group.
  • Move react first.
  • Remove blank lines between groups.
  • Make a separate group for Node.js builtins.
  • Make a separate group for style imports.
  • Separate ./ and ../ imports.
  • Not use groups at all and only sort alphabetically.

groups is an array of arrays of strings:

type Options = {
  groups: Array<Array<string>>;
};

Each string is a regex (with the u flag) and defines a group. (Remember to escape backslashes – it’s "\\w", not "\w", for example.)

Each import is matched against all regexes on the from string. The import ends up in the group with the longest match. In case of a tie, the first matching group wins.

If an import ends up in the wrong group – try making the desired group regex match more of the from string, or use negative lookahead ((?!x)) to exclude things from other groups.

Imports that don’t match any regex are grouped together last.

Side effect imports have \u0000 prepended to their from string (starts with \u0000). You can match them with "^\\u0000".

Type imports have \u0000 appended to their from string (ends with \u0000). You can match them with "\\u0000$" – but you probably need more than that to avoid them also being matched by other groups.

The inner arrays are joined with one newline; the outer arrays are joined with two (creating a blank line).

Every group is sorted internally as mentioned in Sort order. Side effect imports are always placed first in the group and keep their internal order. It’s recommended to keep side effect imports in their own group.

These are the default groups:

[
  // Side effect imports.
  ["^\\u0000"],
  // Packages.
  // Things that start with a letter (or digit or underscore), or `@` followed by a letter.
  ["^@?\\w"],
  // Absolute imports and other imports such as Vue-style `@/foo`.
  // Anything not matched in another group.
  ["^"],
  // Relative imports.
  // Anything that starts with a dot.
  ["^\\."],
];

The astute reader might notice that the above regexes match more than their comments say. For example, "@config" and "_internal" are matched as packages, but none of them are valid npm package names. ".foo" is matched as a relative import, but what does ".foo" even mean? There’s little gain in having more specific rules, though. So keep it simple!

See the examples for inspiration.

Comment and whitespace handling

When an import/export is moved through sorting, its comments are moved with it. Comments can be placed above an import/export (except the first one – more on that later), or at the start or end of its line.

Example:

// comment before import chunk
/* c1 */ import c from "c"; // c2
// b1
import b from "b"; // b2
// a1

/* a2
 */ import a /* a3 */ from "a"; /* a4 */ /* not-a
*/ // comment after import chunk

⬇️

// comment before import chunk
// a1
/* a2
 */ import a /* a3 */ from "a"; /* a4 */ 
// b1
import b from "b"; // b2
/* c1 */ import c from "c"; // c2
/* not-a
*/ // comment after import chunk

Now compare these two examples:

// @flow
import b from "b";
// a
import a from "a";
// eslint-disable-next-line import/no-extraneous-dependencies
import b from "b";
// a
import a from "a";

The // @flow comment is supposed to be at the top of the file (it enables Flow type checking for the file), and isn’t related to the "b" import. On the other hand, the // eslint-disable-next-line comment is related to the "b" import. Even a documentation comment could be either for the whole file, or the first import. So this plugin can’t know if it should move comments above the first import or not (but it knows that the //a comment belongs to the "a" import).

For this reason, comments above and below chunks of imports/exports are never moved. You need to do so yourself, if needed.

Comments around imported/exported items follow similar rules – they can be placed above an item, or at the start or end of its line. Comments before the first item or newline stay at the start, and comments after the last item stay at the end.

import { // comment at start
  /* c1 */ c /* c2 */, // c3
  // b1

  b as /* b2 */ renamed
  , /* b3 */ /* a1
  */ a /* not-a
  */ // comment at end
} from "wherever";
import {
  e,
  d, /* d */ /* not-d
  */ // comment at end after trailing comma
} from "wherever2";
import {/* comment at start */ g, /* g */ f /* f */} from "wherever3";

⬇️

import { // comment at start
/* a1
  */ a, 
  // b1
  b as /* b2 */ renamed
  , /* b3 */ 
  /* c1 */ c /* c2 */// c3
/* not-a
  */ // comment at end
} from "wherever";
import {
  d, /* d */   e,
/* not-d
  */ // comment at end after trailing comma
} from "wherever2";
import {/* comment at start */ f, /* f */g/* g */ } from "wherever3";

If you wonder what’s up with the strange whitespace – see “The sorting autofix causes some odd whitespace!”

Speaking of whitespace – what about blank lines? Just like comments, it’s difficult to know where blank lines should go after sorting. This plugin went with a simple approach – all blank lines in chunks of imports/exports are removed, except in /**/ comments and the blank lines added between the groups mentioned in Sort order. (Note: For exports, blank lines between groups are completely up to you – if you have blank lines around the grouping comments they are preserved.)

(Since blank lines are removed, you might get slight incompatibilities with the lines-around-comment and padding-line-between-statements rules – I don’t use those myself, but I think there should be workarounds.)

The final whitespace rule is that this plugin puts one import/export per line. I’ve never seen real projects that intentionally puts several imports/exports on the same line.

FAQ

Does it support require?

No. This is intentional to keep things simple. Use some other sorting rule, such as import/order, for sorting require.

Why sort on from?

Some other import sorting rules sort based on the first name after import, rather than the string after from. This plugin intentionally sorts on the from string to be git diff friendly.

Have a look at this example:

import { productType } from "./constants";
import { truncate } from "./utils";

Now let’s say you need the arraySplit util as well:

import { productType } from "./constants";
import { arraySplit, truncate } from "./utils";

If the imports were sorted based on the first name after import (“productType” and “arraySplit” in this case), the two imports would now swap order:

import { arraySplit, truncate } from "./utils";
import { productType } from "./constants";

On the other hand, if sorting based on the from string (like this plugin does), the imports stay in the same order. This prevents the imports from jumping around as you add and remove things, keeping your git history clean and reducing the risk of merge conflicts.

Is sorting imports/exports safe?

Mostly.

Imports and re-exports can have side effects in JavaScript, so changing the order of them can change the order that those side effects execute in. It is best practice to either import a module for its side effects or for the things it exports (and never rely on side effects from re-exports).

// An `import` that runs side effects:
import "some-polyfill";

// An `import` that gets `someUtil`:
import { someUtil } from "some-library";

Imports that are only used for side effects stay in the input order. These won’t be sorted:

import "b";
import "a";

Imports that both export stuff and run side effects are rare. If you run into such a situation – try to fix it, since it will confuse everyone working with the code. If that’s not possible, it’s possible to ignore (parts of) sorting.

Another small caveat is that you sometimes need to move comments manually – see Comment and whitespace handling.

For completeness, sorting the imported/exported items of an import is always safe:

import { c, b, a } from "wherever";
// Equivalent to:
import { a, b, c } from "wherever";

Note: import {} from "wherever" is not treated as a side effect import.

Finally, there’s one more thing to know about exports. Consider this case:

one.js:

export const title = "One";
export const one = 1;

two.js:

export const title = "Two";
export const two = 2;

reexport.js:

export * from "./one.js";
export * from "./two.js";

main.js:

import * as reexport from "./rexport.js";
console.log(reexport);

What happens if you run main.js? In Node.js and browsers the result is:

{
  one: 1,
  two: 2,
}

Note how title is not even present in the object! This is good for sorting, because it means that it’s safe to reorder the two export * from exports in reexport.js – it’s not like the last import “wins” and you’d accidentally change the value of title by sorting.

However, this might still cause issues depending on which bundler you use. Here’s how a few bundlers handled the duplicate name title the time of this writing:

  • ✅ Webpack: Compile time error – safe.
  • ✅ Parcel: Run time error – safe.
  • ⚠️ Rollup: Compile time warning, but uses the first one of them so it’s potentially unsafe. It’s possible to configure Rollup to treat warnings as errors, though.
  • ✅ TypeScript: Compile time error – safe.

The sorting autofix causes some odd whitespace!

You might end up with slightly weird spacing, for example a missing space after a comma:

import {bar, baz,foo} from "example";

Sorting is the easy part of this plugin. Handling whitespace and comments is the hard part. The autofix might end up with a little odd spacing around an import/export sometimes. Rather than fixing those spaces by hand, I recommend using Prettier or enabling other autofixable ESLint whitespace rules. See examples for more information.

The reason the whitespace can end up weird is because this plugin re-uses and moves around already existing whitespace rather than removing and adding new whitespace. This is to stay compatible with other ESLint rules that deal with whitespace.

Can I use this without autofix?

Not really. The error message for this rule is literally “Run autofix to sort these imports!” Why? To actively encourage you to use autofix, and not waste time on manually doing something that the computer does a lot better. I’ve seen people painstakingly fixing cryptic (and annoying!) sorting errors from other rules one by one, not realizing they could have been autofixed. Finally, not trying to make more detailed messages makes the code of this plugin much easier to work with.

How do I use eslint-ignore for this rule?

Looking for /* eslint-disable */ for this rule? Read all about ignoring (parts of) sorting.

How is this rule different from import/order?

The import/order rule used to not support alphabetical sorting but now it does. So what does eslint-plugin-simple-import-sort bring to the table?

Some other differences:

  • This plugin gives you a single error for each chunk of imports/exports, while import/order can give multiple (see Can I use this without autofix? for details). In other words, this plugin is noisier in terms of underlined lines in your editor, while import/order is noisier in terms of error count.
  • This plugin has a single (though very powerful) option that is a bunch of regexes, while import/order has bunch of different options. It’s unclear which is easier to configure. But eslint-plugin-simple-import-sort tries to do the maximum out of the box.

License

MIT