Biome 10 🧹 Import Organization — The built-in assist action - KandZ

⏱️ Estimated read: 12 min | |

Biome’s import organization is not a linter rule and not a formatter option. It is an assist action, and the assist is the third tool in the Biome toolchain alongside the formatter and the linter. The distinction matters because the assist actions always come with a code fix—they are not meant to catch bugs or impose a coding style, they are meant to improve the code quality and the developer experience by applying the safe, automatic corrections . The organizeImports action is the one that sorts the imports and the exports, removes the unused ones, and merges the duplicate ones, and it is enabled by default as part of the recommended assist set .

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The action is configured under the assist.actions.source.organizeImports key in the biome.json, and the value is "on" or "off". In Biome 2.x, the older top-level organizeImports.enabled key was replaced by the nested key under the assist, and the biome migrate command is the mechanism that ports the old configuration to the new structure . The action is safe, which means that the fix does not change the runtime behavior of the program, and the safe fix is the reason the action can be applied on save without the manual review.

Key point: organizeImports is a Biome assist action, not a linter rule and not a formatter option. It sorts the imports and the exports by the source categories, removes the unused imports, and merges the duplicate imports. It is enabled by default and configured under assist.actions.source.organizeImports. The action can be disabled per file with the // biome-ignore assist/source/organizeImports comment or with the overrides array.

Why the import organization is a separate action

The assist problem. The linter rules catch the bugs, and the formatter rules format the code. The import organization is neither—it is the refactoring that changes the order and the structure of the imports without changing the runtime behavior. The assist is the mechanism that performs the safe refactoring, and the organizeImports is the assist action that owns the import sorting .

The chunk problem. The action does not sort the entire file as a single list. It divides the imports and the exports into the chunks, and the chunk is a sequence of the adjacent imports or the exports. The action never moves the imports across the chunk boundaries, and the boundaries are the non-import statements, the bare imports, and the detached comments . The chunk is the mechanism that respects the code structure, and the sorting is the within-chunk operation.

The group problem. The action sorts the imports by the source categories. The categories are the :NODE: for the Node.js built-ins, the :BUN: for the Bun built-ins, the :PACKAGE: for the npm packages, the :ALIAS: for the aliases, the :RELATIVE: for the relative paths, and the :URL: for the URLs . The group configuration is the mechanism that customizes the category order, and the glob patterns are the mechanism that defines the custom groups.

The unsafe problem. The action is safe by default, and the safe fix is the reason it can be applied on save. The unused import removal and the duplicate merge are the safe fixes, and the useImportType rule is the separate lint rule that enforces the import type syntax . The safe fix is the mechanism that keeps the action trustworthy, and the lint rule is the mechanism that enforces the type import style.

a. The configuration and the default behavior

The organizeImports action is configured under the assist.actions.source object. The "on" enables the action, and the "off" disables it. The action is enabled by default, and the explicit configuration is the mechanism that documents the intent .

// biome.json — the import organization configuration
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

The "on" is the default, and the configuration above is the explicit form. The action runs when the biome check command is used, and the --write flag is the mechanism that applies the fix. The biome format and the biome lint commands do not organize the imports; only the biome check does .

The action can be disabled for the whole project with the "off" value. The disable is the mechanism for the project that wants the sorting but not the unused removal, or the project that wants the imports untouched.

// biome.json — the disabled import organization
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "off"
      }
    }
  }
}

The "off" disables the action, and the imports are not sorted. The explicit disable is the mechanism that turns off the action without the suppression comments.

The action can be disabled for a specific file with the suppression comment. The comment is placed on the first import, and the biome-ignore directive is the mechanism that suppresses the action for the file .

// biome-ignore assist/source/organizeImports: organized by hand
import B from "b";
import A from "a";

The comment suppresses the action, and the imports are not organized. The suppression is the mechanism for the hand-sorted barrel file, and the comment is the explicit documentation of the intent.

b. The group customization and the chunk boundaries

The action sorts the imports by the source categories, and the groups option is the mechanism that customizes the category order. The groups are matched in the order they are listed, and the first matching group wins .

// biome.json — the custom groups
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "options": {
            "groups": [
              ":NODE:",
              ":PACKAGE:",
              ":RELATIVE:"
            ]
          }
        }
      }
    }
  }
}

The :NODE: group is the Node.js built-ins, the :PACKAGE: group is the npm packages, and the :RELATIVE: group is the relative paths. The order is the sort order, and the groups are the mechanism that customizes the category order. The :BLANK_LINE: is the mechanism that adds the blank line between the groups .

The sortBareImports option is the mechanism that sorts the bare imports. The bare import is the import "polyfill" that has no bindings, and the default is to keep the bare imports in place. The sortBareImports: true is the mechanism that sorts them, and the { "kind": "bare" } group is the mechanism that places them at the chosen position .

// biome.json — the bare import sorting
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "options": {
            "sortBareImports": true,
            "groups": [
              ":NODE:",
              ":PACKAGE:",
              { "kind": "bare" },
              ":RELATIVE:"
            ]
          }
        }
      }
    }
  }
}

The sortBareImports: true enables the sorting, and the { "kind": "bare" } group is the position. The bare imports are the side-effect imports, and the sorting is the mechanism that orders them with the rest.

The chunk boundaries are the mechanism that respects the code structure. The action never moves the imports across the non-import statements, the bare imports, and the detached comments. The blank lines alone do not create the chunk boundaries, and the detached comment followed by the blank line is the mechanism that forces the new chunk .

// The chunk boundary
import A from "a";
import * as B from "b";
// chunk 1

import "polyfill";
// The bare import creates its own chunk.

// Detached comment (followed by a blank line)
// New chunk starts here
import { C } from "c";

The chunks are the mechanism that keeps the imports in the logical groups, and the boundary is the mechanism that prevents the action from reordering the imports that the developer intentionally separated.

Complete Example Session

// ============================================
// PART 1: THE BASIC IMPORT ORGANIZATION
// ============================================

// The unorganized imports:
import { A } from "./file.js";
import { db } from "@mycompany/db";
import { Button } from "@mycompany/ui";
import { handler } from "./handler.js";

// The organized imports:
import { db } from "@mycompany/db";
import { Button } from "@mycompany/ui";

import { A } from "./file.js";
import { handler } from "./handler.js";

// The packages are grouped before the relative imports.

// ============================================
// PART 2: THE CONFIGURATION
// ============================================

// biome.json
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

// The action is enabled.
// The biome check --write applies it.

// ============================================
// PART 3: THE DISABLED ACTION
// ============================================

// biome.json
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "off"
      }
    }
  }
}

// The action is disabled.
// The imports are not sorted.

// ============================================
// PART 4: THE SUPPRESSION COMMENT
// ============================================

// biome-ignore assist/source/organizeImports: organized by hand
import B from "b";
import A from "a";

// The comment suppresses the action for the file.
// The imports are not organized.

// ============================================
// PART 5: THE CUSTOM GROUPS
// ============================================

// biome.json
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "options": {
            "groups": [":NODE:", ":PACKAGE:", ":RELATIVE:"]
          }
        }
      }
    }
  }
}

// The Node.js built-ins are first.
// The packages are second.
// The relative imports are last.

// ============================================
// PART 6: THE BARE IMPORT SORTING
// ============================================

// biome.json
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "options": {
            "sortBareImports": true,
            "groups": [":PACKAGE:", { "kind": "bare" }, ":RELATIVE:"]
          }
        }
      }
    }
  }
}

// The bare imports are sorted and placed after the packages.

// ============================================
// PART 7: THE TYPE IMPORT GROUPING
// ============================================

// biome.json
{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "options": {
            "groups": [":PACKAGE:", ":RELATIVE:", ":TYPES:"]
          }
        }
      }
    }
  }
}

// The type imports are grouped at the end.

// ============================================
// PART 8: THE UNUSED IMPORT REMOVAL
// ============================================

// The input:
import { unused } from "./unused.js";
import { used } from "./used.js";

// The output:
import { used } from "./used.js";

// The unused import is removed by the action.

// ============================================
// PART 9: THE DUPLICATE IMPORT MERGE
// ============================================

// The input:
import { A } from "my-package";
import { B } from "my-package";

// The output:
import { A, B } from "my-package";

// The duplicate imports are merged.

// ============================================
// PART 10: THE CHECKLIST
// ============================================

// [ ] The action is configured under assist.actions.source.organizeImports.
// [ ] The action is enabled by default.
// [ ] The biome check --write applies the action.
// [ ] The suppression comment disables the action for a file.
// [ ] The custom groups define the category order.
// [ ] The sortBareImports option sorts the side-effect imports.

The ten parts covered the basic import organization, the configuration, the disabled action, the suppression comment, the custom groups, the bare import sorting, the type import grouping, the unused import removal, the duplicate import merge, and the checklist. The through-line is that the action is the assist, and the configuration is the group order.

Quick Reference

The configuration

Key	Values	Default
`assist.actions.source.organizeImports`	`"on"`, `"off"`	`"on"`

The source categories

Category	Matches
`:NODE:`	The Node.js built-ins
`:BUN:`	The Bun built-ins
`:PACKAGE:`	The npm packages
`:ALIAS:`	The aliases
`:RELATIVE:`	The relative paths
`:URL:`	The URLs
`:TYPES:`	The type imports

The options

Option	Purpose
`groups`	The category order
`sortBareImports`	Sort the side-effect imports
`identifierOrder`	The named import sort order

The suppression

Mechanism	Purpose
`// biome-ignore assist/source/organizeImports`	Disable the action for a file
The `overrides` array	Disable the action for the file globs

Best Practices

✅ Do This:

// Use the default configuration
{ "assist": { "actions": { "source": { "organizeImports": "on" } } } } // ✅

// Use the suppression comment for the hand-sorted file
// biome-ignore assist/source/organizeImports: organized by hand      // ✅

❌ Don’t Do This:

# Use biome format or biome lint to organize imports
biome format --write ./src # does not organize the imports           // ❌

# Assume the action is a linter rule
biome lint --write ./src # does not organize the imports             // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The imports are not sorted	The `biome format` or `biome lint` is used	Use `biome check --write`
The hand-sorted file is re-sorted	No suppression	Add the `biome-ignore` comment
The type imports are not grouped	The `:TYPES:` group is missing	Add the group to the `groups` array
The bare imports are moved	The `sortBareImports` is enabled	Disable the option

Real-World Examples

1. The default configuration

{ "assist": { "actions": { "source": { "organizeImports": "on" } } } }

2. The disabled action

{ "assist": { "actions": { "source": { "organizeImports": "off" } } } }

3. The suppression comment

// biome-ignore assist/source/organizeImports: organized by hand

4. The custom groups

{ "groups": [":NODE:", ":PACKAGE:", ":RELATIVE:"] }

5. The bare import sorting

{ "sortBareImports": true }

6. The type import grouping

{ "groups": [":PACKAGE:", ":TYPES:", ":RELATIVE:"] }

7. The unused import removal

import { used } from "./used.js";

8. The duplicate import merge

import { A, B } from "my-package";

9. The chunk boundary

// The blank line alone does not split the chunk.
// The detached comment followed by the blank line does.

10. The CLI command

biome check --write ./src

Visual

The Assist Action

┌──────────────────────────────────────────────────────────────┐
│  THE ORGANIZE IMPORTS IS AN ASSIST ACTION                    │
│                                                              │
│  Source file                                                 │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The assist action   │  Sorts the imports                 │
│  │ organizes the       │  Removes the unused                │
│  │ imports             │  Merges the duplicates             │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The biome check     │  The action is enforced            │
│  │ --write applies it  │                                    │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Chunk Boundary

┌──────────────────────────────────────────────────────────────┐
│  THE CHUNK BOUNDARIES                                        │
│                                                              │
│  import A from "a";                                          │
│  import B from "b";                                          │
│  // chunk 1                                                  │
│                                                              │
│  import "polyfill";                                          │
│  // The bare import creates its own chunk.                   │
│                                                              │
│  // Detached comment                                         │
│  // New chunk starts here                                    │
│  import C from "c";                                          │
│                                                              │
│  The action does not move the imports across the boundaries. │
└──────────────────────────────────────────────────────────────┘

The Group Order

┌──────────────────────────────────────────────────────────────┐
│  THE GROUP ORDER                                             │
│                                                              │
│  groups: [":NODE:", ":PACKAGE:", ":RELATIVE:"]               │
│                                                              │
│  :NODE:      The Node.js built-ins                           │
│  :PACKAGE:   The npm packages                                │
│  :RELATIVE:  The relative paths                              │
│                                                              │
│  The first matching group wins.                              │
│  The imports that match no group are placed at the end.      │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
The action	The `organizeImports` assist
The configuration	`assist.actions.source.organizeImports`
The default	`"on"`
The categories	`:NODE:`, `:BUN:`, `:PACKAGE:`, `:ALIAS:`, `:RELATIVE:`, `:URL:`, `:TYPES:`
The chunk	The sequence of the adjacent imports
The suppression	The `biome-ignore` comment
The CLI	`biome check --write`

Key takeaways:

The import organization is a Biome assist action, not a linter rule. The assist actions always come with a code fix, and the organizeImports is the one that sorts the imports and the exports . It is enabled by default and configured under assist.actions.source.organizeImports.
The action sorts within the chunks. The chunk is a sequence of the adjacent imports or exports, and the action never moves the imports across the non-import statements, the bare imports, and the detached comments . The chunk is the mechanism that respects the code structure.
The group configuration customizes the category order. The :NODE:, the :PACKAGE:, the :RELATIVE:, and the other categories are matched in the order they are listed, and the first matching group wins . The custom groups are the mechanism that defines the project-specific order.
The action is enabled by default and applied by the biome check --write. The biome format and the biome lint commands do not organize the imports, and the biome check is the command that runs the assist . The --write flag is the mechanism that applies the fix.
The action can be suppressed per file. The // biome-ignore assist/source/organizeImports comment is the mechanism that disables the action for the hand-sorted file, and the overrides array is the mechanism that disables it for the file globs .

Remember: The Biome import organization is the assist action, not the linter rule and not the formatter option. The action sorts the imports within the chunks, groups them by the source categories, removes the unused ones, and merges the duplicates. The assist.actions.source.organizeImports is the configuration, and the biome check --write is the command. The suppression comment is the mechanism for the exceptions.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!