Diagnosing Biome Import Sorting Failures in TypeScript and JavaScript Projects

Recognizable Condition

You run biome format or biome check on a TypeScript or JavaScript file, but the imports remain unsorted or grouped incorrectly even though organizeImports.enabled = true is set in your biome.json. No error is reported, yet the import order does not match Biome's documented grouping: external packages, internal aliases, relative imports, side‑effect imports.

Cause and Diagnostic Table

#	Possible Cause	Quick Verification
1	Configuration missing or overridden by overrides	Check that organizeImports exists at the root of biome.json and is not disabled in an override block.
2	File matched by ignore patterns	Inspect biome.json ignore array and cross‑reference with .gitignore.
3	Language‑specific settings disabled	Ensure javascript.organizeImports.enabled and typescript.organizeImports.enabled are not explicitly set to false.
4	Conflicting editor formatter (Prettier, ESLint) running on save	Review IDE settings: VS Code editor.defaultFormatter should be biomejs.biome.

Ordered Verification Steps

1. Run Biome with unsafe fixes on a single file to see if it proposes import changes:

   biome check --apply-unsafe src/example.ts

   Run from the repository root. Requires read/write access to the file. If Biome outputs a diff that reorders imports, the engine works; the problem is configuration or environment.
2. Validate the configuration file:

   biome validate-config

   Run in the same directory as biome.json. Errors here indicate syntax or schema problems that silently disable features.
3. Confirm the file is not ignored:

   biome check --files-ignore-unknown=true src/example.ts

   The flag forces Biome to evaluate the file even if it matches an ignore pattern. If imports are sorted now, adjust your ignore globs.
4. Check Biome version — import sorting behavior changed in v1.5 (group ordering) and v1.8 (side‑effect imports):

   biome --version

   Note the version; if older than 1.8, side‑effect imports may be reordered incorrectly.
5. Test with a minimal configuration: Create a temporary biome.json containing only:

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

   Run biome check --apply-unsafe --config-path=./temp-biome.json src/example.ts. If sorting works, your main config has an overriding setting.

Fixes Tied to Findings

• Missing root organizeImports: Add "organizeImports": { "enabled": true } at the top level of biome.json.
• File ignored: Remove the file/path from ignore array or tighten the glob (e.g., change "**/dist/**" to "dist/**").
• Language‑specific override: Explicitly set "javascript": { "organizeImports": { "enabled": true } }, "typescript": { "organizeImports": { "enabled": true } } in biome.json.
• Competing formatter: In VS Code, set "editor.defaultFormatter": "biomejs.biome" and disable format‑on‑save for Prettier/ESLint extensions.
• Outdated Biome: Upgrade to the latest stable (npm update -g @biomejs/biome or via your package manager) to get improved sorting algorithm and side‑effect handling.

Escalation Criteria

If imports still refuse to sort after completing all checks, gather the following and file a bug report on the Biome repository:

• Biome version (biome --version)
• Minimal reproduction repository (or a zip with biome.json, package.json, and the offending file)
• Output of biome check --verbose src/example.ts

Escalate to your team lead if the issue blocks CI pipelines or causes recurring merge conflicts due to inconsistent formatting across contributors.

Limitations and Version‑Specific Behavior

• Prior to Biome v1.9, import type vs import distinction is not respected for grouping. Verify your version if type‑only imports appear in the wrong group.
• Side‑effect imports (e.g., import './polyfill') may be reordered unless marked with /* biome-ignore lint/organizeImports/noSideEffectImports */.
• Migration from ESLint/Prettier via biome migrate eslint does not preserve custom import‑order rules; manual adjustment is usually required.
• Monorepos with multiple biome.json files can produce inconsistent sorting if the root config lacks organizeImports and package‑level configs differ.

Practical Verification Checklist

1. Run biome check --apply-unsafe src/**/*.ts and inspect the diff for import reordering.
2. Create a test file with deliberately unsorted imports, run biome format --write test.ts, and verify output matches expected group order.
3. Open the file in VS Code with the Biome extension, trigger format‑on‑save, and observe import sorting in real time.
4. Add a CI step: biome check --no-errors-on-unmatched src/ to fail the build on import‑sorting violations.

Note: This guide reflects Biome behavior up to v1.9. Some behaviors may change in newer releases; always verify against the version in your project.