shared-tooling-biome

Biome

Quick Guide: Biome is a unified linter, formatter, and import organizer for JavaScript, TypeScript, JSX, TSX, JSON, CSS, and GraphQL. Single Rust binary replaces ESLint + Prettier with 97% Prettier compatibility. Use biome.json for all configuration. Run biome check --write to lint, format, and organize imports in one pass. Use biome ci in pipelines.

Current stable version: Biome v2.4.x (March 2026). Biome v2 introduced type-aware linting, nested configs, and a revamped import organizer.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use biome.json or biome.jsonc for ALL configuration — Biome does not use JavaScript config files)

(You MUST pin Biome to an exact version with --save-exact — Biome formatting can change between versions)

(You MUST use biome ci in CI pipelines, NOT biome check — ci is read-only with no --write flag)

(You MUST use biome check --write for local development — runs linter, formatter, and import organizer in one pass)

(You MUST include $schema in biome.json for editor autocompletion and validation)

</critical_requirements>

Auto-detection: Biome, biome.json, biome.jsonc, @biomejs/biome, biome check, biome lint, biome format, biome ci, biome-ignore, organizeImports, biome migrate

When to use:

• Setting up a unified linter + formatter for JavaScript/TypeScript projects
• Replacing ESLint + Prettier with a single, faster tool
• Greenfield projects wanting zero-config or minimal-config setup
• Large codebases where linting/formatting speed matters
• Configuring import organizing with custom group ordering
• Migrating from ESLint and/or Prettier to Biome
• Setting up CI pipelines with biome ci
• Configuring pre-commit hooks with Biome's --staged flag

When NOT to use:

• Projects requiring ESLint plugins with no Biome equivalent (e.g., custom framework-specific plugins)
• Projects heavily invested in custom ESLint rules that cannot be replicated
• Projects needing Markdown, YAML, or TOML formatting (Biome does not support these yet)
• Runtime code (this is build-time tooling only)
• Git hooks framework setup (Husky/Lefthook configuration is a separate concern)
• TypeScript compiler configuration (tsconfig.json is a separate concern)

Key patterns covered:

• biome.json configuration with formatter, linter, and assist settings
• Linter rule groups (recommended, all, nursery) and severity levels
• Formatter configuration (indent style, line width, quotes, semicolons)
• Import organizer with custom group ordering
• CLI commands: check, format, lint, ci, migrate
• Migration from ESLint + Prettier
• Git hooks integration (Husky, Lefthook, --staged flag)
• CI integration with GitHub Actions and GitLab CI
• Editor integration (VS Code, JetBrains)
• Suppression comments (biome-ignore, biome-ignore-all, range suppressions)
• Nested configuration for monorepos
• Overrides for file-specific settings

Examples

• [Setup & Configuration](examples/core.md) — Installation, biome.json, VS Code, monorepos, framework configs
• [Linting Rules](examples/linting.md) — Rule groups, domains, suppressions, overrides, import ordering
• [Formatting](examples/formatting.md) — Formatter options, Prettier compatibility, option mapping
• [CI & Git Hooks](examples/ci.md) — GitHub Actions, GitLab CI, Husky, Lefthook, staged files
• [Migrating from ESLint/Prettier](examples/migration.md) — Automated migration, rule mapping, package cleanup

Other resources:

• [CLI Quick Reference](reference.md) — All CLI commands, flags, and configuration option tables

<philosophy>

Philosophy

Biome unifies linting, formatting, and import organizing into a single tool with a single configuration file. Built in Rust, it delivers 20x faster performance than ESLint + Prettier while maintaining 97% Prettier compatibility.

Core principles:

1. One tool, one config — biome.json replaces .eslintrc, prettier.config, and import sorting plugins
2. Sensible defaults — Biome works out of the box with recommended rules enabled; zero-config is a valid setup
3. Speed as a feature — Rust-powered binary processes large codebases in milliseconds, not seconds
4. Unified commands — biome check --write runs everything in one pass (lint + format + organize imports)
5. Safe by default — Safe fixes apply automatically; unsafe fixes require explicit --unsafe flag

</philosophy>

<patterns>

Core Patterns

Pattern 1: Basic biome.json Configuration

Every Biome project starts with a biome.json at the project root. Use biome init to scaffold one, then customize.

# Install Biome (always pin exact version)
npm install --save-dev --save-exact @biomejs/biome

# Create default biome.json
npx @biomejs/biome init

// biome.json — minimal recommended setup
{
  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
  "linter": { "rules": { "recommended": true } },
  "assist": {
    "enabled": true,
    "actions": { "source": { "organizeImports": "on" } },
  },
}

Why good: $schema enables editor autocompletion, VCS integration respects .gitignore, explicit indentStyle: "space" avoids Biome's tab default, recommended rules provide a strong baseline

// BAD: No schema, no VCS, relying on defaults that differ from Prettier
{ "linter": { "enabled": true } }

Why bad: Missing $schema loses autocompletion, no VCS means linting node_modules, Biome defaults to tabs which surprises Prettier migrants

Full example: See [examples/core.md](examples/core.md) for a production-ready biome.json with overrides, framework configs, and monorepo setup.

Pattern 2: Linter Rules Configuration

Biome provides 459+ rules across 8 groups (accessibility, complexity, correctness, nursery, performance, security, style, suspicious). Rules default to recommended — a curated subset of safe, stable rules. Severity levels: "off", "on", "info", "warn", "error". See [reference.md](reference.md#linter-rule-groups) for the full rule groups and severity tables.

Domains (Technology-Specific Rules)

Biome v2 introduces domains that group rules by technology. Domains auto-detect from package.json dependencies.

{ "linter": { "domains": { "react": "recommended", "test": "recommended" } } }

Full examples: See [examples/linting.md](examples/linting.md) for rule configuration, suppressions, overrides, and import ordering.

Pattern 3: Formatter Configuration

Biome's formatter achieves 97% Prettier compatibility. Global settings apply to all languages; language-specific settings override globals. Biome defaults to tabs — set indentStyle: "space" explicitly when migrating from Prettier.

{
  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
  "javascript": {
    "formatter": { "quoteStyle": "double", "semicolons": "always" },
  },
  "json": { "formatter": { "trailingCommas": "none" } },
  "css": { "formatter": { "enabled": true } },
}

Full reference: See [examples/formatting.md](examples/formatting.md) for all options, Prettier mapping, and language-specific settings.

Pattern 4: Import Organizer

Biome v2 revamped the import organizer with custom group ordering. Configure under assist.actions.source.organizeImports.

{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              [":BUN:", ":NODE:"],
              ":PACKAGE:",
              ":BLANK_LINE:",