Architecture Note: Enforcing Import Order with Biome importSort

The problem: inconsistent imports create noisy reviews

When multiple developers add imports in different orders, pull requests accumulate unrelated reordering changes. Reviewers spend time on import placement instead of logic, and merge conflicts become more likely in shared files. Biome's importSort rule addresses this by grouping and ordering import declarations according to categories you define.

Useful takeaway

Declare importSort under rules in biome.json, run biome check --json . to detect violations, and use biome format --write . only after you have verified the categories match your repository's module layout. Do not assume path aliases or TypeScript path mappings are resolved automatically.

Requirements

• A Node.js or JavaScript/TypeScript project with Biome installed.
• A biome.json configuration file at the project root.
• Read access to the files Biome inspects; write access if you run formatting commands.
• An agreed import category model: external packages, internal modules, sibling files, parent directories, and type-only imports.

Smallest suitable design

Start with a minimal rule that separates external imports from local ones:

{
  "linter": {
    "rules": {
      "import": {
        "importSort": {
          "level": "warn",
          "groups": [
            {
              "type": "external",
              "members": ["*"]
            },
            {
              "type": "internal",
              "members": ["@app/*"]
            },
            {
              "type": "sibling",
              "members": ["*"]
            }
          ]
        }
      }
    }
  }
}

This configuration tells Biome to evaluate imports in three groups. The level field sets severity: warn reports violations without failing the command, while error makes biome check exit with a non-zero status. Place this rule inside the linter.rules.import namespace in biome.json.

Trust and data boundaries

Biome resolves import groups through string matching against the import specifier. It does not read TypeScript tsconfig.json path mappings or webpack aliases unless those aliases are expressed as literal strings in your pattern list. An import such as import { utils } from "/@/lib/utils" will not match @app/* unless your configuration explicitly includes @/* or the exact alias.

Trust boundaries are local to the file system. Biome reads source files and writes formatting changes only when explicitly invoked. It does not send import graphs to a remote service by default.

Operational checks

1. Open a terminal in the project root where biome.json lives.
2. Run biome check --json .. This reads files and emits JSON without modifying them.
3. Inspect the output for objects whose rule field is import/importSort. Each entry includes a file path, range, and diagnostic message.
4. To apply fixes, run biome format --write .. This rewrites files in place.
5. Review the resulting diff in version control before committing.

Required permissions: read access for biome check; read and write access for biome format --write. Risk: --write overwrites files. If you do not use version control, back up the working tree first.

Failure modes

• Indirect imports and path aliases: If your codebase uses barrel files or deep aliases, string-based groups may place imports in the wrong category or leave them ungrouped.
• Extended presets: If biome.json extends a preset that also configures importSort, your rule may be overridden or merged in unexpected ways. Verify the effective configuration after any extends declaration.
• File system watchers: Biome uses incremental parsing to avoid re-parsing unchanged files, but network-mounted or rapidly changing directories can trigger re-evaluation and slower CI runs.
• Severity drift: A rule set to warn will not block merges. Move to error only after the codebase is clean and the team agrees on the categories.

Comparison: check versus format

Command	Changes files?	Use case
biome check --json .	No	CI gating, local inspection, previews of violations
biome format --write .	Yes	Applying import order and formatting after rules are stable

Conditions that would change the design

• If you use TypeScript path aliases, add explicit string patterns for each alias or consider disabling automatic sorting for those files.
• If your repository is a monorepo with multiple biome.json files, decide whether each workspace owns its import groups or whether a root configuration applies everywhere.
• If CI runs on network-attached storage, test incremental parsing performance before enabling importSort at error level.
• If import cycles are a concern, combine importSort with dependency graph tooling; sorting alone does not prevent circular imports.

Practical verification

After changing biome.json, run biome check --json . and confirm that the import/importSort diagnostics match your expectations. Then run biome format --write . on a single file or directory, inspect the diff, and verify that external, internal, and sibling imports appear in the intended order. If the output does not change, your group patterns may not match the actual import specifiers.

Rollback for biome format --write: use your version control system to restore files, for example git checkout -- . or the equivalent in your VCS. There is no built-in undo command in Biome.