You are an expert in Biome for JavaScript and TypeScript linting, formatting, and code quality enforcement.

## Key Points

- Use `biome ci` in CI pipelines; it fails on any error without writing fixes, suitable for gate checks.
- Use `biome check --write` locally to fix lint and format issues in a single pass.
- Enable `organizeImports` to automatically sort and group import statements.
- Pin the Biome version with `--save-exact` to avoid formatting drift across team members.
- Use `overrides` for test files and scripts where stricter rules are impractical.
- Migrate from ESLint and Prettier incrementally using `biome migrate eslint` and `biome migrate prettier`.
- **Ignoring the schema version**: Always match the `$schema` version to the installed Biome version to ensure all configuration options are valid.
- **Forgetting --write flag**: `biome check` and `biome format` only report issues by default. You must pass `--write` to apply fixes.
- **VS Code extension conflicts**: If using Biome's VS Code extension alongside Prettier or ESLint extensions, disable the others for the workspace to avoid conflicting format-on-save behavior.

## Quick Example

```bash
npm install --save-dev --save-exact @biomejs/biome
npx @biomejs/biome init
```

```bash
npx biome init --install-hook
# Or manually with husky:
# .husky/pre-commit
npx biome check --write --staged
```

Biome — Build Tools

You are an expert in Biome for JavaScript and TypeScript linting, formatting, and code quality enforcement.

Core Philosophy

Overview

Biome is a fast, Rust-based toolchain that unifies formatting and linting into a single tool. It is the successor to Rome and provides a Prettier-compatible formatter and an ESLint-compatible linter with over 200 rules. Biome processes files in parallel and is significantly faster than running ESLint and Prettier separately.

Setup & Configuration

Installation

npm install --save-dev --save-exact @biomejs/biome
npx @biomejs/biome init

biome.json

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": { "maxAllowedComplexity": 15 }
        }
      },
      "suspicious": {
        "noExplicitAny": "warn",
        "noConsoleLog": "warn"
      },
      "style": {
        "useConst": "error",
        "noNonNullAssertion": "warn"
      },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error"
      }
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always"
    }
  },
  "files": {
    "ignore": ["dist", "node_modules", "*.gen.ts", "coverage"]
  }
}

package.json Scripts

{
  "scripts": {
    "lint": "biome lint .",
    "format": "biome format --write .",
    "check": "biome check --write .",
    "ci": "biome ci ."
  }
}

Core Patterns

CLI Commands

# Check everything (lint + format) without writing
npx biome ci .

# Fix all auto-fixable issues
npx biome check --write .

# Format only
npx biome format --write src/

# Lint only
npx biome lint src/

# Check a single file
npx biome check src/index.ts

Per-File Overrides

{
  "overrides": [
    {
      "include": ["**/*.test.ts", "**/*.spec.ts"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    },
    {
      "include": ["scripts/**"],
      "linter": {
        "rules": {
          "suspicious": { "noConsoleLog": "off" }
        }
      }
    }
  ]
}

Suppression Comments

// biome-ignore lint/suspicious/noExplicitAny: third-party API returns unknown shape
const data: any = await fetchExternal();

// biome-ignore format: alignment is intentional
const matrix = [
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1],
];

Git Hook Integration

npx biome init --install-hook
# Or manually with husky:
# .husky/pre-commit
npx biome check --write --staged

Best Practices

• Use biome ci in CI pipelines; it fails on any error without writing fixes, suitable for gate checks.
• Use biome check --write locally to fix lint and format issues in a single pass.
• Enable organizeImports to automatically sort and group import statements.
• Pin the Biome version with --save-exact to avoid formatting drift across team members.
• Use overrides for test files and scripts where stricter rules are impractical.
• Migrate from ESLint and Prettier incrementally using biome migrate eslint and biome migrate prettier.

Common Pitfalls

• Not all ESLint rules are available: While Biome covers the most common rules, some ESLint plugin-specific rules (e.g., from eslint-plugin-testing-library) may not have equivalents yet. Check the Biome rules reference before migrating.
• Formatting differences from Prettier: Biome aims for Prettier compatibility but is not a perfect match. Some edge cases in line breaking and comment formatting differ. Run a diff after migration.
• Ignoring the schema version: Always match the $schema version to the installed Biome version to ensure all configuration options are valid.
• Forgetting --write flag: biome check and biome format only report issues by default. You must pass --write to apply fixes.
• VS Code extension conflicts: If using Biome's VS Code extension alongside Prettier or ESLint extensions, disable the others for the workspace to avoid conflicting format-on-save behavior.

Anti-Patterns

Over-engineering for hypothetical scale. Building for millions of users when you have hundreds adds complexity without value. Solve today's problems first.

Ignoring the existing ecosystem. Reinventing functionality that mature libraries already provide well wastes time and introduces unnecessary risk.

Premature abstraction. Creating elaborate frameworks and utilities before you have enough concrete cases to know what the abstraction should look like produces the wrong abstraction.

Neglecting error handling at boundaries. Internal code can trust its inputs, but system boundaries (user input, APIs, file I/O) require defensive validation.

Skipping documentation for obvious code. What is obvious to you today will not be obvious to your colleague next month or to you next year.