/shared-tooling-biome

name: shared-tooling-biome
description: Biome v2 unified linter, formatter, and import organizer — single Rust-powered tool replacing ESLint + Prettier with 97% Prettier compatibility and 20x faster performance

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 au