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. source is also often called specifier in the JavaScript ecosystem.

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

Chunk of imports and chunk 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.

1
// chunk 1
2
import A from "a";
3
import * as B from "b";
4
import { C } from "c";
5
// chunk 2
6
export * from "d";
7
export * as F from "e";
8
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:

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

Imports 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 type { namedTypeImport } from "same-source";
4
import defaultNamespaceCombined, * as namespaceCombined from "same-source";
5
import defaultNamedCombined, { namedCombined } from "same-source";
6
import defaultImport from "same-source";
7
import type defaultTypeImport from "same-source";
8
import { importWithAttribute } from "same-source" with { "attribute": "value" } ;

is sorted as follows:

1
import { importWithAttribute } from "same-source" with { "attribute": "value" } ;
2
import type * as namespaceTypeImport from "same-source";
3
import type defaultTypeImport from "same-source";
4
import type { namedTypeImport } from "same-source";
5
import * as namespaceImport from "same-source";
6
import defaultNamespaceCombined, * as namespaceCombined from "same-source";
7
import defaultImport from "same-source";
8
import defaultNamedCombined, { namedCombined } 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 as explained in the following section.

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
An object matcher, or
A list of glob patterns, predefined group matchers, and object matchers.

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:: sources starting with https:// and http://.

Let’s take an example. In the default configuration, Node.js modules without the node: protocol 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 fs from "fs";
3
import path from "node:path";
4
import { test } from "node:test";
5
import scopedLibUsingJsr from "jsr:@scoped/lib";
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.

Group matchers can also be glob patterns and list of glob patterns. Glob patterns select 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/**. Note that the predefined groups can also be negated. !:NODE: matches all sources that don’t match :NODE:. For more details on the supported glob patterns, see the dedicated section.

Finally, group matchers can be object matchers. An object matcher allows to match type-only imports and exports.

Given the following configuration:

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

The following code:

1
import type { T } from "@my/lib";
2
import { V } from "@my/lib";

is sorted as follows:

1
import { V } from "@my/lib";
2
import type { T } from "@my/lib";

The object matcher { "type": false, "source": ["@my/lib", "@my/lib/**"] } match against imports and exports without the type keyword with a source that matches one of the glob pattern of the list ["@my/lib", "@my/lib/**"].

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
            [":BUN:", ":NODE:"],
5
            ":BLANK_LINE:",
6
            ["@my/lib", "@my/lib/**", "!@my/lib/special", "!@my/lib/special/**"],
7
            "@/**"
8
        ]
9
    }
10
}

…the following code…

1
import test from "bun:test";
2
import path from "node:path";
3
import lib from "@my/lib";
4
import libPath from "@my/lib/path";
5
import libSpecial from "@my/lib/special";
6
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";

Groups are matched in order. This means that one group matcher can shadow succeeding groups. For example, in the following configuration, the group matcher :URL: is never matched because all imports and exports match the first matcher **.

1
{
2
    "options": {
3
        "groups": [
4
            "**",
5
            ":URL:"
6
        ]
7
    }
8
}

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

Import and export merging

The organizer also merges imports and exports that can be merged.

For example, the following code:

1
import type { T1 } from "package";
2
import type { T2 } from "package";
3
import * as ns from "package";
4
import D1 from "package";
5
import D2 from "package";
6
import { A } from "package";
7
import { B } from "package";

is merged as follows:

1
import type { T1, T2 } from "package";
2
import D1, * as ns from "package";
3
import D2, { A, B } from "package";

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.

Common configurations

This section provides some examples of common configurations.

Placing `import type` and `export type` at the start of the chunks

1
{
2
    "options": {
3
        "groups": [
4
            { "type": true }
5
        ]
6
    }
7
}

Note that you can want to use the lint rule useImportType and its style to enforce the use of import type instead of import { type }.

Placing `import type` and `export type` at the end of the chunks

1
{
2
    "options": {
3
        "groups": [
4
            { "type": false }
5
        ]
6
    }
7
}

How to configure

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