Use Biome's organizeImports to replace separate import sorting

The problem: one file, three tools

You open a pull request and see three different import styles in one file: a relative path mixed with an absolute alias, an unused utility imported at the top, and a formatting rule that wants a blank line where your editor just inserted one. If your project runs Prettier, ESLint, and a separate import-sorting plugin, you are parsing the same file multiple times and maintaining multiple configurations just to keep imports tidy.

Biome's organizeImports action sorts, groups, and removes unused imports as part of its formatting pass, using a single AST per file. For teams trying to cut tool sprawl without losing import hygiene, it can replace a separate import organizer - provided you test its glob overrides and accept that its rule set is not a one-to-one ESLint replacement.

What organizeImports actually does

Biome parses a file once into a shared abstract syntax tree (AST), then applies formatting and lint rules against that same tree instead of spinning up separate processes. organizeImports is part of the formatter, not a lint rule. When enabled, it reorders import statements, groups them by origin, and drops imports that are not used in the file.

Because formatting and import organization run together, saving a file in your editor can apply both changes in a single pass rather than asking Prettier to reformat and ESLint to re-sort separately.

Worked example: enable and run it

Assuming Biome CLI v1.x, add the formatter option to your project's biome.json:

{
  "formatter": {
    "organizeImports": {
      "enabled": true
    }
  }
}

Here is a TypeScript file before the change:

import { z } from "zod";
import { helper } from "./utils/helper";
import { unused } from "./utils/unused";
import { User } from "@/types/user";
import { formatDate } from "@/lib/date";

After running Biome, unused imports are removed and the remaining imports are ordered and grouped. Exact grouping depends on your Biome version and configuration, so treat the result as an example, not a guaranteed output:

import { z } from "zod";
import { User } from "@/types/user";
import { formatDate } from "@/lib/date";
import { helper } from "./utils/helper";

Run the command

Open a terminal at your project root and run:

biome check --write src/index.ts

• Where: your terminal, at the project root directory.
• Permissions: read and write access to the target file.
• Placeholder: replace src/index.ts with the file or directory you want to format.
• Expected check: Biome rewrites the file so imports are ordered, grouped, and unused imports are removed.
• Risk: --write mutates files on disk. Review changes with git diff before committing. If the result is wrong, roll back with git checkout -- src/index.ts.

Limitations to check before adopting

• Rule coverage is not one-to-one with ESLint. Custom ESLint plugins and complex rules may have no direct Biome equivalent.
• Glob semantics differ. Biome's file inclusion, exclusion, and override patterns can behave differently from ESLint ignore rules, so test your biome.json includes and excludes explicitly.
• Version sensitivity. CLI flags and the configuration schema evolve between releases, so older tutorials may describe behavior that has changed. Pin Biome in your package manager and CI configuration.

Practical verification

1. Run biome config --explain to list active rules and compare them against the fields you set in biome.json.
2. Enable the Biome language server in your editor and trigger format on save to confirm lint and format apply together.
3. Run biome check --write on a single directory first, review the git diff, and only then enable it repository-wide.

Action: try it on one directory first

If your goal is fewer configuration files and faster editor feedback, enable organizeImports on one directory, run biome check --write, and inspect the diff. If the import ordering matches your team's style and the unused-import removal does not delete anything you need, expand the scope. If it does not, you have lost only one directory's worth of formatting, not your entire build pipeline.