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

biome.jsonc

(You MUST pin Biome to an exact version with

--save-exact

(You MUST use

biome ci

biome check

ci

--write

(You MUST use

biome check --write

(You MUST include

$schema

</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 — Installation, biome.json, VS Code, monorepos, framework configs
• Linting Rules — Rule groups, domains, suppressions, overrides, import ordering
• Formatting — Formatter options, Prettier compatibility, option mapping
• CI & Git Hooks — GitHub Actions, GitLab CI, Husky, Lefthook, staged files
• Migrating from ESLint/Prettier — Automated migration, rule mapping, package cleanup

Other resources:

• CLI Quick Reference — All CLI commands, flags, and configuration option tables

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

Core Patterns

Pattern 1: Basic biome.json Configuration

Every Biome project starts with a

biome.json

biome init

# 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

.gitignore

indentStyle: "space"

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

Why bad: Missing

$schema

Full example: See 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

recommended

"off"

"on"

"info"

"warn"

"error"

Domains (Technology-Specific Rules)

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

package.json

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

Full examples: See 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"

{
  "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 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:",
              ["@company/**"],
              ":BLANK_LINE:",
              ":ALIAS:",
              ":PATH:",
              ":BLANK_LINE:",
              { "type": true },
            ],
            "identifierOrder": "natural",
          },
        },
      },
    },
  },
}

Key options:

identifierOrder

"natural"

var1, var2, var11

"lexicographic"

"@my/lib/**"

{ "type": true, "source": ["@my/lib"] }

Predefined Groups

:NODE:

node:

:BUN:

:PACKAGE:

:PACKAGE_WITH_PROTOCOL:

:ALIAS:

@/

#

~

$

%

:PATH:

:URL:

:BLANK_LINE:

Full examples: See examples/linting.md for import ordering with results.

Pattern 5: CLI Commands

Use

check

ci

npx biome check --write .          # Lint + format + organize imports (auto-fix)
npx biome ci .                     # CI mode (read-only, optimized for pipelines)
npx biome check --staged --write . # Pre-commit hooks (only staged files)
npx biome check --changed --since=main .  # Changed files only

Full reference: See examples/ci.md for complete CLI usage, filtering, and reporting options.

Pattern 6: Suppression Comments

Biome uses

biome-ignore

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

// biome-ignore-all lint/style/noDefaultExport: framework requires default export (top of file only)

// biome-ignore-start lint/suspicious/noDoubleEquals: legacy section
// biome-ignore-end lint/suspicious/noDoubleEquals: legacy section

See reference.md for the full suppression syntax table and specifier levels. See examples/linting.md for inline, file-level, and range suppression examples.

Pattern 7: Nested Configuration (Monorepos)

Biome v2 supports nested

biome.json

// packages/my-app/biome.json — inherits from root
{ "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json", "extends": "//" }

// packages/legacy-lib/biome.json — relaxes rules
{
  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
  "root": false,
  "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } },
}

Why good:

"extends": "//"

"root": false

Full examples: See examples/core.md for root + child config patterns.

Pattern 8: Overrides (File-Specific Rules)

Use

overrides

{
  "overrides": [
    {
      "includes": ["**/*.test.ts", "**/*.test.tsx"],
      "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } },
    },
    {
      "includes": ["**/app/**/page.tsx", "**/app/**/layout.tsx"],
      "linter": { "rules": { "style": { "noDefaultExport": "off" } } },
    },
  ],
}

Why good: Overrides eliminate suppression comments in every file, test files get relaxed rules, framework conventions handled declaratively

Full examples: See examples/linting.md for test, config, and generated file overrides.

Performance

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

Approximate benchmarks. Actual performance varies by project size and rule configuration.

Performance Tips:

• 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

Type-Aware Linting Performance:

Biome v2 introduced type-aware linting without the TypeScript compiler. Enable selectively:

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

<decision_framework>

Decision Framework

Biome vs ESLint + Prettier

Need linting and formatting?
|-- Greenfield project?
|   |-- Want simplest possible setup? -> Biome (one tool, one config)
|   |-- Need niche ESLint plugins? -> ESLint + Prettier
|   +-- Speed is important? -> Biome (20x faster)
|-- Existing ESLint + Prettier project?
|   |-- Happy with current setup? -> Stay with ESLint + Prettier
|   |-- Config complexity is a pain? -> Migrate to Biome
|   |-- Need ESLint plugins without Biome equivalents? -> Stay
|   +-- Want faster CI/pre-commit hooks? -> Biome (or hybrid)
+-- Monorepo?
    |-- Need per-package lint configs? -> Biome v2 nested configs or ESLint 10
    +-- Speed bottleneck in CI? -> Biome

Configuration Complexity

How to configure Biome?
|-- Just starting out? -> Run `biome init`, use defaults with recommended: true
|-- Migrating from ESLint? -> Run `biome migrate eslint --write`
|-- Migrating from Prettier? -> Run `biome migrate prettier --write`
|-- Need per-file rules?
|   |-- Different rules for test files? -> Use `overrides` in biome.json
|   +-- Different rules per package? -> Use nested biome.json with "root": false
+-- Need custom import ordering? -> Configure organizeImports.options.groups

Full migration decision tree: See examples/migration.md.

</decision_framework>

Integration Guide

Works with:

• JSX/TSX: Full support with

  react

  domain for React-specific lint rules
• 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

CI/editor integration: See examples/ci.md and examples/core.md.

<red_flags>

RED FLAGS

High Priority Issues:

• Using

  biome check

  in CI instead of

  biome ci

  (

  check

  allows

  --write

  which is dangerous in pipelines;

  ci

  is read-only)
• Not pinning Biome version with

  --save-exact

  (formatting can change between minor versions, causing diff noise)
• Missing

  $schema

  in biome.json (loses editor autocompletion, validation, and discoverability)
• Using JavaScript config files instead of biome.json (Biome only supports JSON/JSONC configuration)
• Running

  biome format

  and

  biome lint

  separately when

  biome check

  does both (wastes time, parses files twice)

Medium Priority Issues:

• Forgetting to set

  indentStyle: "space"

  when migrating from Prettier (Biome defaults to tabs)
• Not enabling VCS integration (without it, Biome may process node_modules and dist)
• Using

  --unsafe

  without reviewing changes (unsafe fixes can alter program behavior)
• Not including

  --no-errors-on-unmatched

  in git hooks (causes failures when no matching files are staged)
• Enabling all nursery rules (they are experimental and may have bugs or performance 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

biome.jsonc

(You MUST pin Biome to an exact version with

--save-exact

(You MUST use

biome ci

biome check

ci

--write

(You MUST use

biome check --write

(You MUST include

$schema

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

</critical_reminders>