git:20260316.063411a to git:20260316.02848e0

---

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

- 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 needing Markdown, YAML, or TOML formatting (Biome does not support these yet)

- Runtime code (this is build-time tooling only)

- Git hooks setup details (see `shared-tooling-git-hooks` for Husky/Lefthook patterns)

- TypeScript compiler configuration (see `shared-tooling-typescript-config`)

**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

- For ESLint + Prettier configuration (alternative approach), see `shared-tooling-eslint-prettier`

- For git hooks and lint-staged, see `shared-tooling-git-hooks`

- For TypeScript compiler configuration, see `shared-tooling-typescript-config`

- For daily coding conventions (naming, imports, constants), see CLAUDE.md

---

<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

**When to use Biome:**

- Greenfield projects wanting a single, fast tool

- Projects where ESLint + Prettier configuration complexity is a burden

- Large codebases where linting/formatting speed matters

- Teams wanting zero-config or minimal-config setup

- Projects needing JS/TS/JSX/TSX/JSON/CSS/GraphQL support

**When NOT to use Biome:**

- Projects requiring niche ESLint plugins with no Biome equivalent

- Projects needing Markdown, YAML, or TOML formatting

- Projects heavily invested in custom ESLint rules that cannot be replicated

- Teams requiring ESLint's mature plugin ecosystem (accessibility plugins, framework-specific rules)

</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.

```bash

# Install Biome (always pin exact version)

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

# Create default biome.json

npx @biomejs/biome init

```

```jsonc

{

"$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",

"assist": {

"enabled": true,

},

}

```

```jsonc

```

---

### Pattern 2: Linter Rules Configuration

#### Rule Groups

| Group | Purpose | Default |

| --------------- | ------------------------------------ | ------------------ |

| `accessibility` | Prevents a11y problems | recommended |

| `complexity` | Simplifies overly complex code | recommended |

| `correctness` | Detects guaranteed errors | recommended |

| `nursery` | Experimental rules (opt-in required) | off |

| `performance` | Catches inefficient patterns | recommended |

| `security` | Identifies security flaws | recommended |

| `style` | Enforces consistent code style | recommended (warn) |

| `suspicious` | Flags likely incorrect patterns | recommended |

#### Severity Levels

| Level | Behavior |

| --------- | ---------------------------------- |

| `"off"` | Rule disabled |

| `"on"` | Default severity for that rule |

| `"info"` | Informational, no CLI exit impact |

| `"warn"` | Non-blocking diagnostic |

| `"error"` | Blocks CLI with non-zero exit code |

#### Domains (Technology-Specific Rules)

```jsonc

```

---

### Pattern 3: Formatter Configuration

```jsonc

{

"javascript": {

},

}

```

---

### Pattern 4: Import Organizer

```jsonc

{

"assist": {

"actions": {

"source": {

"organizeImports": {

"level": "on",

"options": {

"groups": [

":NODE:",

":PACKAGE:",

":BLANK_LINE:",

["@company/**"],

":BLANK_LINE:",

":ALIAS:",

{ "type": true },

],

},

},

},

},

},

}

```

#### Predefined Groups

| Group | Matches |

| -------------- | ------------------------------------------ |

| `:NODE:` | Node.js built-ins and `node:` protocol |

| `:PACKAGE:` | Regular npm packages |

| `:ALIAS:` | Aliased imports (`@/`, `#`, `~`, `$`, `%`) |

| `:URL:` | HTTP/HTTPS imports |

| `:BUN:` | Bun-specific modules |

| `:BLANK_LINE:` | Visual separator between groups |

---

### Pattern 5: CLI Commands

```bash

```

---

### Pattern 6: Suppression Comments

```typescript

// biome-ignore lint/suspicious/noDebugger: needed for local debugging

debugger;

```

---

### Pattern 7: Nested Configuration (Monorepos)

```jsonc

```

```jsonc

{

"$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",

"root": false,

}

```

---

### Pattern 8: Overrides (File-Specific Rules)

Use `overrides` for file-pattern-specific configuration without nested config files.

```jsonc

{

"overrides": [

{

},

{

"includes": ["**/app/**/page.tsx", "**/app/**/layout.tsx"],

},

],

}

```

</patterns>

---

<performance>

## Performance

Biome is written in Rust and processes files in parallel, making it significantly faster than JavaScript-based alternatives.

| Tool | Format Time (1000 files) | Lint Time (1000 files) |

| ----------------- | ------------------------ | ---------------------- |

| Biome | ~100ms | ~200ms |

| Prettier | ~2000ms | N/A |

| ESLint | N/A | ~3000ms |

| ESLint + Prettier | ~5000ms | ~5000ms |

_Approximate benchmarks. Actual performance varies by project size and rule configuration._

- **Use `biome check`** instead of running `biome format` and `biome lint` separately — single pass is faster

- **Enable VCS integration** to automatically skip ignored files (`.gitignore`)

- **Use `--staged` or `--changed`** in hooks and CI to process only affected files

- **Be selective with nursery rules** — some experimental rules may impact performance

- **Use `--profile-rules`** (v2.4+) to identify slow lint rules in your configuration

- **Default scan** discovers nested configs only (fast)

- **Project domain scan** indexes the full module graph (slower, but still faster than tsc)

- **Types domain scan** adds type inference (most comprehensive, most expensive)

</performance>

---

<decision_framework>

## Decision Framework

### Biome vs ESLint + Prettier

```

Need linting and formatting?

```

```

How to configure Biome?

```

</decision_framework>

---

<integration>

## Integration Guide

**Works with:**

- **React/Next.js/Remix**: Full JSX/TSX support, domain-specific rules for React

- **TypeScript**: Type-aware linting without tsc dependency (Biome v2+)

- **CSS**: Linting enabled by default, formatting opt-in

- **JSON/JSONC**: Full support including tsconfig.json, package.json

- **GraphQL**: Linting enabled by default, formatting opt-in

- **Vue/Svelte/Astro**: Experimental support via `html.experimentalFullSupportEnabled` (v2.4+)

**Replaces / Conflicts with:**

- **ESLint**: Biome replaces ESLint for linting (or use hybrid approach)

- **Prettier**: Biome replaces Prettier for formatting

- **eslint-plugin-import**: Biome's import organizer replaces import sorting plugins

- **eslint-config-prettier**: Not needed — Biome has no formatter/linter conflicts

</integration>

---

<red_flags>

## RED FLAGS

**High Priority Issues:**

**Medium Priority Issues:**

**Common Mistakes:**

- Using `"root": true` in a nested config (this is the default; use `"root": false` for child configs)

- Expecting Markdown/YAML formatting support (Biome does not support these languages yet)

- Not running `biome migrate --write` when upgrading major versions (config schema changes between v1 and v2)

- Suppression comments without explanations (`biome-ignore lint:` requires text after the colon)

**Gotchas & Edge Cases:**

- Biome defaults to tabs, not spaces — always set `indentStyle` explicitly when migrating from Prettier

- CSS and GraphQL formatting is disabled by default — must opt in with `"formatter": { "enabled": true }`

- `biome-ignore-all` must be at the top of the file — placing it mid-file triggers an unused suppression warning

- Import organizer is part of `assist`, not `linter` — configure under `assist.actions.source.organizeImports`

- The `--staged` flag makes lint-staged unnecessary for Biome-only setups (since Biome v1.7.0+)

- Type-aware linting (project/types domains) triggers file scanning which can slow down first runs on large projects

- `biome migrate eslint --write` does not migrate inspired rules by default — use `--include-inspired` to include them

- Range suppressions (`biome-ignore-start`/`biome-ignore-end`) must have matching rule specifiers

- Biome treats all JS/TS/JSX/TSX under the `javascript` config key — there is no separate `typescript` section

- Configuration files named `.biome.json` (with leading dot) are also discovered (v2.4+)

</red_flags>

---

<critical_reminders>

## CRITICAL REMINDERS

> **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)**

**Failure to follow these rules will cause inconsistent formatting, broken CI pipelines, and missed lint errors.**

</critical_reminders>