Biome 2.x

Overview

Fast, all-in-one toolchain for linting and formatting JavaScript, TypeScript, JSX, and JSON. Biome 2.x replaces ESLint and Prettier with a single, performant tool written in Rust.

Install: pnpm add -D @biomejs/biome

API Reference: Use Context7 MCP for full rule reference and CLI flags (mcp__context7__resolve-library-id → @biomejs/biome ).

Workflows

Initial setup:

• Install Biome: pnpm add -D @biomejs/biome

• Initialize config: pnpm biome init

• Configure biome.json with project standards

• Install VS Code extension: biomejs.biome

• Add npm scripts to package.json

• Test: pnpm biome check .

Migrating from ESLint/Prettier:

• Run migration helper: pnpm biome migrate eslint --write

• Review generated biome.json

• Remove ESLint/Prettier configs and dependencies

• Update pre-commit hooks and CI scripts

• Run full check: pnpm biome check --write .

Daily usage:

• Format on save (VS Code integration)

• Run pnpm biome check . before commits

• Fix auto-fixable issues: pnpm biome check --write .

• Review manual fixes for remaining issues

Configuration

biome.json Structure

{ "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json", "organizeImports": { "enabled": true }, "linter": { "enabled": true, "rules": { "recommended": true } }, "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 }, "javascript": { "formatter": { "quoteStyle": "single", "semicolons": "always", "trailingCommas": "es5", "arrowParentheses": "asNeeded" } }, "files": { "ignore": ["dist", "build", "node_modules", "*.min.js", "coverage"] } }

TypeScript / React Project Config

{ "linter": { "rules": { "recommended": true, "a11y": { "noBlankTarget": "error", "useAltText": "error", "useButtonType": "error" }, "complexity": { "noExcessiveCognitiveComplexity": "warn", "noUselessFragments": "error" }, "correctness": { "noUnusedVariables": "error", "useExhaustiveDependencies": "warn", "useHookAtTopLevel": "error" }, "performance": { "noAccumulatingSpread": "warn" }, "security": { "noDangerouslySetInnerHtml": "warn" }, "style": { "noNonNullAssertion": "warn", "useConst": "error", "useImportType": "error" }, "suspicious": { "noExplicitAny": "error", "noDebugger": "error", "noConsoleLog": "warn" } } }, "javascript": { "formatter": { "jsxQuoteStyle": "double", "quoteStyle": "single" } } }

Per-File Overrides

{ "overrides": [ { "include": ["tests//*.ts"], "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } } }, { "include": ["scripts//*.js"], "formatter": { "lineWidth": 120 } } ] }

CLI Commands

Check (lint + format) — use this for most tasks

pnpm biome check . pnpm biome check --write . # auto-fix pnpm biome check --write --dry-run . # preview changes

Lint or format only

pnpm biome lint --write . pnpm biome format --write .

Diagnostics

pnpm biome rage # effective config + diagnostics pnpm biome explain src/App.tsx # explain failures for a file pnpm biome migrate eslint --write # migrate from ESLint pnpm biome migrate prettier --write # migrate from Prettier

Package.json Scripts

{ "scripts": { "lint": "biome lint .", "format": "biome format --write .", "check": "biome check .", "fix": "biome check --write .", "typecheck": "tsc --noEmit", "quality": "pnpm lint && pnpm typecheck && pnpm build" } }

Editor Integration

VS Code settings.json

{ "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "quickfix.biome": "explicit", "source.organizeImports.biome": "explicit" }, "eslint.enable": false, "prettier.enable": false, "[javascript]": { "editor.defaultFormatter": "biomejs.biome" }, "[typescript]": { "editor.defaultFormatter": "biomejs.biome" }, "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" }, "[json]": { "editor.defaultFormatter": "biomejs.biome" }, "biome.lspBin": "./node_modules/@biomejs/biome/bin/biome" }

Ignoring Code

// biome-ignore lint/suspicious/noExplicitAny: legacy code function legacy(param: any) { return param; }

// biome-ignore format: preserve matrix formatting const matrix = [ 1, 0, 0, 0, 1, 0, 0, 0, 1, ];

Prefer files.ignore in biome.json for ignoring entire directories over inline comments.

Git Hooks Integration

Using lint-staged + Husky:

// package.json { "lint-staged": { "*.{js,jsx,ts,tsx,json}": ["biome check --write --no-errors-on-unmatched"] } }

Using Lefthook (lefthook.yml ):

pre-commit: parallel: true commands: biome: glob: "*.{js,ts,jsx,tsx,json}" run: biome check --write --no-errors-on-unmatched {staged_files}

CI/CD Integration

GitHub Actions

name: Code Quality on: [push, pull_request] jobs: quality: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 with: { version: 10 } - uses: actions/setup-node@v4 with: { node-version: '24', cache: 'pnpm' } - run: pnpm install --frozen-lockfile - run: pnpm biome check . - run: pnpm typecheck

ESLint Rule Equivalents

ESLint Rule Biome Rule

no-unused-vars

correctness/noUnusedVariables

@typescript-eslint/no-explicit-any

suspicious/noExplicitAny

react-hooks/exhaustive-deps

correctness/useExhaustiveDependencies

no-console

suspicious/noConsoleLog

prefer-const

style/useConst

jsx-a11y/alt-text

a11y/useAltText

Best Practices

• Use recommended ruleset as baseline, then customize specific rules

• Enable format-on-save in VS Code for seamless workflow

• Run check before commits using git hooks (Husky/Lefthook)

• Use biome check (not lint + format separately) for unified workflow

• Ignore generated files in biome.json, not inline comments

• Use overrides for different rules in tests vs source

• Commit biome.json to version control for team consistency

• Document custom rules with comments explaining why they're needed

Anti-Patterns

• Running lint and format separately (use check instead)

• Disabling recommended rules without justification

• Using biome-ignore excessively (fix the underlying issue)

• Not committing biome.json to version control

• Mixing ESLint and Biome in the same project

• Ignoring files via inline comments instead of configuration

• Not testing migration thoroughly before removing ESLint/Prettier

• Skipping pre-commit hooks for "quick fixes"

• Using outdated schema version in biome.json

Feedback Loops

Preview formatting changes without writing

pnpm biome format --write --dry-run .

Diagnose config issues

pnpm biome rage

CI test locally (exit code 0 = success)

pnpm biome check . --error-on-warnings && echo "OK"

Verify VS Code integration: Command Palette → "Biome: Show Output Channel" → should show LSP server logs.