Biome Tooling

Biome is a modern, performant toolchain for JavaScript, TypeScript, and related web languages. It combines formatting, linting, and import organization into a single tool that's 15-20x faster than ESLint/Prettier.

Keep ESLint alongside when the project needs plugin-only rules (React hooks, a11y), framework-specific rules (Next.js, Nuxt), or carries heavy custom ESLint configuration.

Hybrid approach: Use Biome for formatting, ESLint for specialized linting.

Core Expertise

What is Biome?

All-in-one toolchain: Linter + formatter + import sorter
Zero-config: Works out of the box with sensible defaults
Fast: Written in Rust, processes files in parallel
Compatible: Matches Prettier formatting 97%+
Supports: JavaScript, TypeScript, JSX, TSX, JSON, CSS

Installation

# Project-local (recommended)
bun add --dev @biomejs/biome

# Verify installation
bunx biome --version

# Initialize configuration
bunx biome init

Essential Commands

# Format files
bunx biome format --write src/

# Lint with fixes
bunx biome lint --write src/

# Check everything (format + lint + organize imports)
bunx biome check --write src/

# Check without changes (CI mode)
bunx biome check src/

# CI mode (exits with error on issues)
bunx biome ci src/

# Migrate from ESLint/Prettier
bunx biome migrate eslint --write
bunx biome migrate prettier --write

# Explain a rule
bunx biome explain noUnusedVariables

Configuration (biome.json)

Minimal Setup (Zero Config)

Biome works without configuration. For basic customization:

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false,
    "ignore": ["dist", "build", "node_modules", ".next", "coverage"]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "organizeImports": {
    "enabled": true
  }
}

Rule Categories

Category	Purpose	Example Rules
`recommended`	Essential rules everyone should enable	Most rules marked "recommended"
`correctness`	Prevent bugs and logic errors	`noUnusedVariables`, `noUnreachable`
`suspicious`	Detect code that might be wrong	`noExplicitAny`, `noDoubleEquals`
`style`	Enforce consistent style	`useConst`, `noVar`
`complexity`	Reduce code complexity	`noForEach`, `useFlatMap`
`performance`	Optimize performance	`noAccumulatingSpread`
`a11y`	Accessibility best practices	`noSvgWithoutTitle`, `useAltText`
`security`	Security vulnerabilities	`noDangerouslySetInnerHtml`

Common Patterns

Ignore Files and Directories

Via biome.json:

{
  "files": {
    "ignore": [
      "dist",
      "build",
      "node_modules",
      "**/*.config.js",
      "scripts/legacy/**"
    ]
  }
}

Via .gitignore (automatic):

{
  "vcs": {
    "enabled": true,
    "useIgnoreFile": true
  }
}

Scope a run to changed files

Both scopes need VCS integration ("vcs": { "enabled": true, "clientKind": "git" }).

Scope	Command	Notes
Staged files only (pre-commit)	`bunx biome check --staged --reporter=github`	Not available on `biome ci`
Committed changes vs a base	`bunx biome check --changed --since=main --reporter=github`	`--since` overrides `vcs.defaultBranch`; without it, set `defaultBranch`

--changed compares committed changes only (staged and unstaged edits are excluded), and it does not follow imports: a changed exported type can break a file that is not in the diff. Run a full biome check before merging when exports change.

For an agent reading the output, combine a scope with --reporter=github (one file:line:col line per diagnostic), --diagnostic-level=error, and --max-diagnostics=N.

Performance Comparison

Tool	Time (1000 files)	Notes
Biome	0.5s	Rust, parallel processing
ESLint	8-10s	Node.js, single-threaded
Prettier	3-5s	Node.js, formatting only
ESLint + Prettier	11-15s	Sequential execution

Agentic Optimizations

Context	Command
Quick check	`bunx biome check src/`
Fix all	`bunx biome check --write src/`
Format only	`bunx biome format --write src/`
Lint only	`bunx biome lint --write src/`
CI mode	`bunx biome ci src/`
Errors only	`bunx biome check --diagnostic-level=error src/`
Limited output	`bunx biome check --max-diagnostics=10 src/`
GitHub reporter	`bunx biome check --reporter=github src/`
Staged files only	`bunx biome check --staged --reporter=github`
Changed vs main	`bunx biome check --changed --since=main --reporter=github`
JSON output	`bunx biome check --reporter=json src/`
Migrate ESLint	`bunx biome migrate eslint --write`
Migrate Prettier	`bunx biome migrate prettier --write`

Quick Reference

Flag	Description
`--write`	Apply fixes/formatting
`--reporter=github`	GitHub annotations format
`--reporter=json`	JSON output
`--diagnostic-level=error`	Errors only
`--max-diagnostics=N`	Limit output count
`--verbose`	Show detailed diagnostics
`--no-errors-on-unmatched`	Ignore unmatched files
`ci`	CI mode (check + exit code)

For detailed examples, advanced patterns, and best practices, see REFERENCE.md.

References

Official docs: https://biomejs.dev
Configuration: https://biomejs.dev/reference/configuration/
Rules: https://biomejs.dev/linter/
Migration guide: https://biomejs.dev/guides/migrate-eslint-prettier/
Editor integration: https://biomejs.dev/

biome-tooling