biome-tooling

# 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 ```bash # Project-local (recommended) bun add --dev @biomejs/biome # Verify installation bunx biome --version # Initialize configuration bunx biome init ``` ## Essential Commands ```bash # 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: ```json { "$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:** ```json { "files": { "ignore": [ "dist", "build", "node_modules", "**/*.config.js", "scripts/legacy/**" ] } } ``` **Via .gitignore (automatic):** ```json { "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](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/