Choosing Biome as a Unified Linter and Formatter for JavaScript Projects

Decision and Constraints

The decision is whether to replace a traditional ESLint + Prettier setup with Biome, a single tool that combines linting and formatting. Constraints include preserving existing lint rules, minimizing configuration effort, and ensuring CI performance does not degrade for a large monorepo.

Option Comparison

Aspect	Biome	ESLint + Prettier
Configuration file	Single biome.json (JSON or TOML)	Two files: .eslintrc.* and .prettierrc
Rule set	Curated defaults; extensible via JSON	Large ecosystem; each rule must be added explicitly
Incremental mode	--watch re‑processes only changed files	Requires plugins (e.g., eslint-watch) for similar behavior
Editor integration	Language Server Protocol (LSP) support in most editors	ESLint and Prettier extensions; separate setup
Migration effort	Map existing ESLint rules to Biome equivalents; formatting rules are built‑in	None if keeping current setup

Trade‑offs

Adopting Biome reduces tooling complexity and can speed up CI because the formatter and linter share a single process. However, you must verify that every ESLint rule you rely on has a comparable Biome rule or can be safely omitted. If your project uses many custom ESLint plugins, the migration may require writing equivalent Biome configurations or retaining ESLint for those specific checks.

Implementation Example

Below is a minimal biome.json that enables the recommended lint rules and adopts the default formatter.

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "style": {
        "noNonNullAssertion": "off"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  }
}

To apply formatting and linting across the codebase, run:

biome check --write

This command will lint files, apply formatting where needed, and overwrite the original files.

Validation Steps

1. Execute biome check --write on a clean working copy.
2. Run git diff --exit-code to see if any files were changed.
3. If changes appear, review them to confirm they match the project’s formatting expectations (e.g., indentation, quote style).
4. For a quick sanity check, format a snippet via stdin:

echo 'const foo =  bar ;' | biome fmt --stdin

The output should be const foo = bar; (adjust according to your indent style).

Limitations and Practical Checks

• Biome’s rule set is smaller than ESLint’s; some niche rules may be missing. Use biome lint --list-rules to verify which rules are available.
• If a required rule is absent, you can keep ESLint for those specific files by adding an eslintignore pattern or running ESLint in a separate CI step.
• Always commit the biome.json file and run the validation steps on a branch before merging to ensure no unintended whitespace or semantic changes are introduced.