organizeImports

JavaScript (and super languages)

Summary

Rule available since: v1.0.0
Diagnostic Category: assist/source/organizeImports
This action is recommended.
The default severity of this rule is information.

How to enable in your editor

1
{
2
  "code_actions_on_format": {
3
    "source.organizeImports.biome": true,
4
  }
5
}

1
{
2
  "editor.codeActionsOnSave": {
3
    "source.organizeImports.biome": "explicit",
4
  }
5
}

Use the source action code source.organizeImports.biome

Description

Provides a code action to sort the imports and exports in the file using a built-in or custom order.

Imports and exports are first separated into chunks, before being sorted. Imports or exports of a chunk are then grouped according to the user-defined groups. Within a group, imports are sorted using a built-in order that depends on the import/export kind, whether the import/export has attributes and the source being imported from.

1
import A from "@my/lib" with { "attribute1": "value" };
2
^^^^^^^^       ^^^^^^^         ^^^^^^^^^^^^^^^^^^^^^
3
  kind         source                attributes
4

5
export * from "@my/lib" with { "attribute1": "value" };
6
^^^^^^^^       ^^^^^^^         ^^^^^^^^^^^^^^^^^^^^^
7
  kind         source                attributes

Note that source is also often called specifier in the JavaScript ecosystem.

Chunk of imports and chunks of exports

A chunk is a sequence of adjacent imports or exports. A chunk contains only imports or exports, not both at the same time. The following example includes two chunks. The first chunk consists of the three imports and the second chunk consists of the three exports. The first export that appears ends the first chunk and starts a new one.

1
import A from "a";
2
import * as B from "b";
3
import { C } from "c";
4
export * from "d";
5
export * as F from "e";
6
export { F } from "f";

Chunks also end as soon as a statement or a side-effect import (also called bare import) is encountered. Every side-effect import forms an independent chunk. The following example contains six chunks:

1
// chunk 1
2
import A from "a";
3
import * as B from "b";
4
// chunk 2
5
import "x";
6
// chunk 3
7
import "y";
8
// chunk 4
9
import { C } from "c";
10
// chunk 5
11
export * from "d";
12
function f() {}
13
// chunk 6
14
export * as E from "e";
15
export { F } from "f";

The first chunk contains the two first import and ends with the appearance of the first side-effect import import "x".
The second chunk contains only the side-effect import import "x".
The third chunk contains only the side-effect import import "y".
The fourth chunk contains a single import; The first export ends it.
The fifth chunk contains the first export; The function declaration ends it.
The sixth chunk contains the last two export.

Chunks are also delimited by detached comments. A detached comment is a comment followed by a blank line. Comments not followed by a blank line are attached comments. Note that blank lines alone are not taken into account when chunking imports and exports. The following example contains a detached comment that splits the imports into two chunks:

1
// Attached comment 1
2
import A from "a";
3

4
// Attached comment 2
5
import * as B from "b";
6
// Detached comment
7

8
import { C } from "c";

The line import { C } from "c" forms the second chunk. The blank line between the first two imports is ignored so they form a single chunk.

The sorter ensures that chunks are separated from each other with a blank lines. Only side-effect imports adjacent to a chunk of imports are not separated by a blank line. The following code…

1
import A from "a";
2
import * as B from "b";
3
import "x";
4
import { C } from "c";
5
export * from "d";
6
// Detached comment
7

8
export * as F from "e";
9
// Attached comment
10
export { F } from "f";

is sorted as:

1
import A from "a";
2
import * as B from "b";
3
import "x";
4
import { C } from "c";
5

6
export * from "d";
7

8
// Detached comment
9

10
export * as F from "e";
11
// Attached comment
12
export { F } from "f";

Also, note that blank lines inside a chunk are ignored and preserved. They can be removed by explicitly defining groups as demonstrated in the next section.

Import and export sorting

Once chunks are formed, imports and exports of each chunk are sorted. Imports and exports are sorted by their source. Sources are ordered by “distance”. Sources that are “farther” from the current module are put on the top, sources “closer” to the user are put on the bottom. This leads to the following order:

URLs such as https://example.org.
Packages with a protocol such as node:path, bun:test, jsr:@my?lib, or npm:lib.
Packages such as mylib or @my/lib.
Aliases: sources starting with @/, #, ~, or %. They usually are Node.js subpath imports or TypeScript path aliases.
Absolute and relative paths.

Two imports/exports with the same source category are sorted using a natural sort order tailored to URLs, packages, and paths. Notably, the order ensures that A < a < B < b. The order takes also numbers into account, e.g. a9 < a10.

For example, the following code…

1
import sibling from "./file.js";
2
import internal from "#alias";
3
import fs from "fs";
4
import { test } from "node:test";
5
import path from "node:path";
6
import parent from "../parent.js";
7
import scopedLibUsingJsr from "jsr:@scoped/lib";
8
import data from "https://example.org";
9
import lib from "lib";
10
import scopedLib from "@scoped/lib";

…is sorted as follows:

1
import data from "https://example.org";
2
import scopedLibUsingJsr from "jsr:@scoped/lib";
3
import path from "node:path";
4
import { test } from "node:test";
5
import scopedLib from "@scoped/lib";
6
import fs from "fs";
7
import lib from "lib";
8
import internal from "#alias";
9
import parent from "../parent.js";
10
import sibling from "./file.js";

If two imports or exports share the same source and are in the same chunk, then they are ordered according to their kind as follows:

Default type import
Default import
Combined default and namespace import
Combined default and named import
Namespace type import / Namespace type export
Namespace import / Namespace export
Named type import / Named type export
Named import / Named export

Also, import and exports with attributes are always placed first. For example, the following code…

1
import * as namespaceImport from "same-source";
2
import type * as namespaceTypeImport from "same-source";
3
import { namedImport } from "same-source";
4
import type { namedTypeImport } from "same-source";
5
import defaultNamespaceCombined, * as namespaceCombined from "same-source";
6
import defaultNamedCombined, { namedCombined } from "same-source";
7
import defaultImport from "same-source";
8
import type defaultTypeImport from "same-source";
9
import { importWithAttribute } from "same-source" with { "attribute": "value" } ;

is sorted as follows:

1
import { importWithAttribute } from "same-source" with { "attribute": "value" } ;
2
import type defaultTypeImport from "same-source";
3
import defaultImport from "same-source";
4
import defaultNamespaceCombined, * as namespaceCombined from "same-source";
5
import defaultNamedCombined, { namedCombined } from "same-source";
6
import type * as namespaceTypeImport from "same-source";
7
import * as namespaceImport from "same-source";
8
import type { namedTypeImport } from "same-source";
9
import { namedImport } from "same-source";

This default order cannot be changed. However, users can still customize how imports and exports are sorted using the concept of groups.

Import and export groups

Imports or exports of a chunk are divided into groups before being sorted with the built-in order described in the previous section. By default every chunk consists of a single group. These default groups and their order may not be to your taste. The sorter provides a groups option that allows you to customize how the chunks are divided into groups. The groups option is a list of group matchers. A group matcher is:

A predefined group matcher, or
A glob pattern, or
A list of glob patterns.

Predefined group matchers are strings in CONSTANT_CASE prefixed and suffixed by :. The sorter provides several predefined group matchers:

:ALIAS:: sources starting with #, @/, ~, or %.
:BUN:: sources starting with the protocol bun: or that correspond to a built-in Bun module such as bun.
:NODE:: sources starting with the protocol node: or that correspond to a built-in Node.js module such as fs or path.
:PACKAGE:: Scoped and bare packages.
:PACKAGE_WITH_PROTOCOL:: Scoped and bare packages with a protocol.
:PATH:: absolute and relative paths.
:URL:

Let’s take an example. In the default configuration, Node.js modules without the node: protocols are separated from those with a protocol. To groups them together, you can use the predefined group :NODE:. Given the following configuration…

1
{
2
    "assist": {
3
        "actions": {
4
            "source": {
5
                "organizeImports": {
6
                    "level": "on",
7
                    "options": {
8
                        "groups": [
9
                            ":URL:",
10
                            ":NODE:"
11
                        ]
12
                    }
13
                }
14
            }
15
        }
16
    }
17
}

…and the following code…

1
import sibling from "./file.js";
2
import internal from "#alias";
3
import fs from "fs";
4
import { test } from "node:test";
5
import path from "node:path";
6
import parent from "../parent.js";
7
import scopedLibUsingJsr from "jsr:@scoped/lib";
8
import data from "https://example.org";
9
import lib from "lib";
10
import scopedLib from "@scoped/lib";

…we end up with the following sorted result where the imports of node:path and the fs Node.js module are grouped together:

1
import data from "https://example.org";
2
import scopedLibUsingJsr from "jsr:@scoped/lib";
3
import path from "node:path";
4
import fs from "fs";
5
import { test } from "node:test";
6
import scopedLib from "@scoped/lib";
7
import lib from "lib";
8
import internal from "#alias";
9
import parent from "../parent.js";
10
import sibling from "./file.js";

Note that all imports that don’t match a group matcher are always placed at the end.

Groups matchers can also be glob patterns and list of glob patterns. Glob patterns selects imports and exports with a source that matches the pattern. In the following example, we create two groups: one that gathers imports/exports with a source starting with @my/lib except @my/lib/speciaal and the other that gathers imports/exports starting with @/.

1
{
2
    "options": {
3
        "groups": [
4
            ["@my/lib", "@my/lib/**", "!@my/lib/special", "!@my/lib/special/**"],
5
            "@/**"
6
        ]
7
    }
8
}

By applying this configuration to the following code…

1
import lib from "@my/lib";
2
import aliased from "@/alias";
3
import path from "@my/lib/special";
4
import test from "@my/lib/path";

…we obtain the following sorted result. Imports with the sources @my/lib and @my/lib/path form the first group. They match the glob patterns @my/lib and @my/lib/** respectively. The import with the source @my/lib/special is not placed in this first group because it is rejected by the exception !@my/lib/special. The import with the source @/alias is placed in a second group because it matches the glob pattern @/**. Finally, other imports are placed at the end.

1
import lib from "@my/lib";
2
import test from "@my/lib/path";
3
import aliased from "@/alias";
4
import path from "@my/lib/special";

Note that @my/lib matches @my/lib but not @my/lib/**. Conversely, @my/lib/subpath matches @my/lib/**, but not @my/lib. So, you have to specify both glob patterns if you want to accept all imports/exports that start with @my/lib. The prefix ! indicates an exception. You can create exceptions of exceptions by following an exception by a regular glob pattern. For example ["@my/lib", "@my/lib/**", "!@my/lib/special", "!@my/lib/special/**", "@my/lib/special/*/accepted/**"] allows you to accepts all sources matching @my/lib/special/*/accepted/**. For more details on the supported glob patterns, see the dedicated section.

For now, it is not possible to mix predefined group matchers and glob patterns inside a list of globs. This is a limitation that we are working to remove.

The sorter allows the separation of two groups with a blank line using the predefined string :BLANK_LINE:. Given the following configuration…

1
{
2
    "options": {
3
        "groups": [
4
            ":NODE:",
5
            ":BLANK_LINE:",
6
            ["@my/lib", "@my/lib/**", "!@my/lib/special", "!@my/lib/special/**"],
7
            "@/**"
8
        ]
9
    }
10
}

…the following code…

1
import path from "node:path";
2
import lib from "@my/lib";
3
import test from "@my/lib/path";
4
import path from "@my/lib/special";
5
import aliased from "@/alias";

…is sorted as:

1
import path from "node:path";
2

3
import lib from "@my/lib";
4
import test from "@my/lib/path";
5
import aliased from "@/alias";
6
import path from "@my/lib/special";

Comment handling

When sorting imports and exports, attached comments are moved with their import or export, and detached comments (comments followed by a blank line) are left where they are.

However, there is an exception to the rule. If a comment appears at the top of the file, it is considered as detached even if no blank line follows. This ensures that copyright notice and file header comments stay at the top of the file.

For example, the following code…

1
// Copyright notice and file header comment
2
import F from "f";
3
// Attached comment for `e`
4
import E from "e";
5
// Attached comment for `d`
6
import D from "d";
7
// Detached comment (new chunk)
8

9
// Attached comment for `b`
10
import B from "b";
11
// Attached comment for `a`
12
import A from "a";

…is sorted as follows. A blank line is automatically added after the header comment to ensure that the attached comment doesn’t merge with the header comment.

1
// Copyright notice and file header comment
2

3
// Attached comment for `d`
4
import D from "d";
5
// Attached comment for `e`
6
import E from "e";
7
import F from "f";
8

9
// Detached comment (new chunk)
10

11
// Attached comment for `a`
12
import A from "a";
13
// Attached comment for `b`
14
import B from "b";

Named imports, named exports and attributes sorting

The sorter also sorts named imports, named exports, as well as attributes. It uses a natural sort order for comparing numbers.

The following code…

1
import { a, b, A, B, c10, c9 } from "a";
2

3
export { a, b, A, B, c10, c9 } from "a";
4

5
import special from  "special" with { "type": "ty", "metadata": "data" };

…is sorted as follows:

1
import { A, a, B, b, c9, c10 } from "a";
2

3
export { A, a, B, b, c9, c10 } from "a";
4

5
import special from  "special" with { "metadata": "data", "type": "ty" };

Supported glob patterns

You need to understand the structure of a source to understand which source matches a glob. A source is divided in source segments. Every source segment is delimited by the separator / or the start/end of the source. For instance src/file.js consists of two source segments: src and file.js.

star * that matches zero or more characters inside a source segment

file.js matches *.js. Conversely, src/file.js doesn’t match *.js

globstar ** that matches zero or more source segments ** must be enclosed by separators / or the start/end of the glob. For example, **a is not a valid glob. Also, ** must not be followed by another globstar. For example, **/** is not a valid glob.

file.js and src/file.js match ** and **/*.js Conversely, README.txt doesn’t match **/*.js because the source ends with .txt.

Use \* to escape *

\* matches the literal * character in a source.

?, [, ], {, and } must be escaped using \. These characters are reserved for possible future use.
Use ! as first character to negate a glob

file.js matches !*.test.js. src/file.js matches !*.js because the source contains several segments.

How to configure

1
{
2
  "assist": {
3
    "actions": {
4
      "source": {
5
        "organizeImports": "on"
6
      }
7
    }
8
  }
9
}