biome（Biome 代码规范）

Biome

Fast, unified linting, formatting, and import organization for JavaScript, TypeScript, JSX, CSS, and GraphQL. Biome 2.4 provides type-aware linting without the TypeScript compiler, GritQL plugins for custom rules, and domain-based rule grouping. Single binary, zero config by default, 97% Prettier compatibility.

Critical Rules

files.ignore DOES NOT EXIST - use files.includes with negation

Biome 2.x only supports files.includes (with an s). There is NO files.ignore, NO files.include (without s), NO files.exclude. Using any of these will throw Found an unknown key errors.

The only valid keys under files are: includes, maxSize, ignoreUnknown. (experimentalScannerIgnores exists but is now marked deprecated in upstream docs and may be removed.)

To exclude files (generated code, vendored files, etc.), use negation patterns in files.includes:

{
  "files": {
    "includes": ["**", "!**/routeTree.gen.ts", "!**/generated/**"]
  }
}

For paths the scanner must skip even when other tools or assists would otherwise touch them, use the !! force-ignore syntax inside files.includes (replaces experimentalScannerIgnores):

{
  "files": {
    "includes": ["**", "!!**/legacy-vendor/**"]
  }
}

Do NOT use overrides with linter/formatter/assists: {enabled: false} to skip generated files - that approach is fragile (easy to miss a subsystem like assists/import organizer) and unnecessarily complex. Just exclude via files.includes.

Always use biome check, not separate lint + format

biome check runs formatter, linter, and import organizer in one pass. Never call biome lint and biome format separately in CI - use biome check (or biome ci for CI mode).

biome.json lives at project root

Every project needs one biome.json at the root. Monorepo packages use nested configs with "extends": "//" to inherit from root. Never use relative paths like "extends": ["../../biome.json"].

Use --write to apply fixes

biome check --write .            # Apply safe fixes only
biome check --write --unsafe .   # Apply all fixes including unsafe (review changes)

--fix exists as an alias for --write on biome lint and biome format, but biome check is the canonical entry point and --write is the documented flag. Stick with --write.

Safe vs unsafe fixes. Removing unused imports, parameters, and variables is classified as unsafe (an external caller could still reference the symbol). Plain --write will leave them in place and report the diagnostic. Use --write --unsafe (and review the diff) or delete them by hand.

Pin exact versions and migrate after upgrades

pnpm add --save-dev --save-exact @biomejs/biome@latest
pnpm biome migrate --write

The $schema URL in biome.json is version-pinned (e.g. "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json"). After bumping @biomejs/biome, the CLI errors with The configuration schema version does not match the CLI version until you run biome migrate --write. Run it as part of the upgrade, not later.

Quick Start

pnpm add --save-dev --save-exact @biomejs/biome
pnpm biome init    # Creates default biome.json with recommended rules

IDE Setup

VS Code - Install biomejs.biome extension:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

source.fixAll.biome applies safe lint fixes on save; source.organizeImports.biome runs the assist. Both are needed for parity with the CLI's biome check --write.

Zed - Biome extension available natively. The inline-config feature (v2.4) lets editors override rules without affecting biome.json. Note the spelling: Zed uses inline_config (snake_case); the VS Code extension uses inlineConfig (camelCase).

{
  "formatter": { "language_server": { "name": "biome" } },
  "lsp": {
    "biome": {
      "settings": {
        "inline_config": {
          "linter": { "rules": { "suspicious": { "noConsole": "off" } } }
        }
      }
    }
  }
}

CI Integration

pnpm biome ci .                                  # No writes, non-zero exit on errors
pnpm biome ci --reporter=default --reporter=github .  # GitHub Actions annotations

Configuration (biome.json)

Recommended config for React/TypeScript projects

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "includes": [
      "src/**/*.ts", "src/**/*.tsx",
      "tests/**/*.ts", "**/*.config.ts", "**/*.json",
      "!**/generated", "!**/components/ui"
    ]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 120
  },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true },
    "domains": { "react": "recommended" }
  },
  "javascript": {
    "formatter": { "quoteStyle": "double" }
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": { "organizeImports": "on" }
    }
  }
}

Formatter options

Key options: indentStyle ("space"/"tab"), indentWidth, lineWidth, lineEnding ("lf"/"crlf"), trailingNewline. JS-specific: quoteStyle, trailingCommas, semicolons, arrowParentheses, bracketSpacing.

Linter rule configuration

Rules use severity levels "error", "warn", "info", or "off". Some accept options:

{
  "linter": {
    "rules": {
      "recommended": true,
      "style": {
        "noRestrictedGlobals": {
          "level": "error",
          "options": {
            "deniedGlobals": {
              "Buffer": "Use Uint8Array for browser compatibility."
            }
          }
        },
        "useComponentExportOnlyModules": "off"
      }
    }
  }
}

Import organizer

The import organizer (Biome Assist) merges duplicates, sorts by distance, and supports custom grouping. As of v2.4.13 it also sorts imports inside TypeScript modules (module "x" {...}) and .d.ts declaration files.

{
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              { "source": "builtin" },
              { "source": "external" },
              { "source": "internal", "match": "@company/*" },
              { "source": "relative" }
            ]
          }
        }
      }
    }
  }
}

Per-subsystem includes

Each subsystem (linter, formatter, assist) has its own includes for fine-grained scoping. Applied after files.includes - can only narrow, not widen.

{
  "files": {
    "includes": ["**", "!**/dist"]
  },
  "linter": {
    "includes": ["**", "!**/components/ui"]
  },
  "formatter": {
    "includes": ["**", "!**/components/ui"]
  }
}

This lints and formats everything except dist/ and components/ui, while assists (import organizer) still run on components/ui.

Overrides

Overrides apply different settings to specific file patterns. Use for per-file rule tweaks (e.g., relaxing rules for vendored/shadcn components). The field is includes (with s).

{
  "overrides": [
    {
      "includes": ["**/components/ui/**"],
      "linter": {
        "rules": {
          "suspicious": { "noDocumentCookie": "off" },
          "style": { "useComponentExportOnlyModules": "off" }
        }
      }
    },
    {
      "includes": ["**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": { "noConsole": "off" }
        }
      }
    }
  ]
}

Monorepo configuration

Root biome.json holds shared config. Package configs inherit with "extends": "//":

{
  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
  "extends": "//"
}

Override specific rules per package by adding a linter.rules section alongside "extends": "//".

Configuration file discovery (v2.4)

Search order: biome.json -> biome.jsonc -> .biome.json -> .biome.jsonc -> platform config home.

Platform config home paths:

Other v2.4 highlights

• Embedded snippets: Biome 2.4 formats and lints CSS and GraphQL embedded inside JavaScript (e.g. styled-components, Emotion, gql template literals). Works automatically; no extra config.
• Vue/Svelte parser improvements: substantially fewer false positives in noUnusedVariables, useConst, useImportType, and noUnusedImports inside .vue and .svelte files.

Domains

Domains group lint rules by technology. Enable only what your stack needs:

{
  "linter": {
    "domains": {
      "react": "recommended",
      "next": "recommended",
      "test": "recommended",
      "types": "all"
    }
  }
}

Activation levels: "recommended" (stable rules only), "all" (includes nursery), "none" (disable).

The project domain enables rules needing the module graph. The types domain (v2.4) enables rules requiring type inference. Both trigger a file scan that adds a small overhead.

Type-Aware Linting

Biome 2.0 introduced type-aware linting without the TypeScript compiler. Biome has its own type inference engine in Rust - no typescript dependency needed.

How it works

Enable the types domain to activate file scanning and type inference. Performance impact is minimal compared to typescript-eslint because inference runs natively.

v2.4.12 improvements: type-aware rules now resolve members through the Pick<T, K>, Omit<T, K>, Partial<T>, Required<T>, and Readonly<T> utility types (preserving optional, readonly, and nullable flags), so rules see the same shape your code does.

Key rules

noFloatingPromises

The most impactful type-aware rule. Detects unhandled promises:

// ERROR: floating promise
async function loadData() {
  fetch("/api/data");
}

// VALID: awaited
async function loadData() {
  await fetch("/api/data");
}

// VALID: explicitly voided (fire-and-forget)
async function loadData() {
  void fetch("/api/data");
}

Detects ~75% of cases compared to typescript-eslint, improving each release. v2.4.12 added detection through cross-module generic wrapper functions (e.g. a generic wrap(fn) re-exported from another file).

React Compiler interaction with useExhaustiveDependencies

If you use the React Compiler, useExhaustiveDependencies cannot tell that the compiler is handling memoization for you. Many React Compiler users (including Biome contributors) disable the rule entirely:

{
  "linter": {
    "rules": {
      "correctness": {
        "useExhaustiveDependencies": "off"
      }
    }
  }
}

If you keep the rule on, expect to suppress effects that intentionally depend on a value but don't read it in the body (e.g. location.pathname to re-trigger on navigation).

Limitations vs typescript-eslint

• Complex generic type inference may miss some cases
• Not a full type checker - handles common patterns, not every edge case
• Rules still in nursery - expect improvements with each release
• Major performance advantage: fraction of tsc-based linting time

GritQL Custom Rules

GritQL is a declarative pattern-matching language for custom lint rules. Create .grit files and register them as plugins.

{ "plugins": ["./lint-rules/no-object-assign.grit"] }

Examples

Ban Object.assign:

`$fn($args)` where {
    $fn <: `Object.assign`,
    register_diagnostic(
        span = $fn,
        message = "Prefer object spread instead of `Object.assign()`"
    )
}

CSS - enforce color classes:

language css;
`$selector { $props }` where {
    $props <: contains `color: $color` as $rule,
    not $selector <: r"\.color-.*",
    register_diagnostic(
        span = $rule,
        message = "Don't set explicit colors. Use `.color-*` classes instead."
    )
}

Plugin API

register_diagnostic() arguments:

• severity - "hint", "info", "warn", "error" (default: "error")
• message (required) - diagnostic message
• span (required) - syntax node to highlight

Supported target languages: JavaScript (default) and CSS, plus JSON since v2.4 (the v2.4 release blog adds JSON; the linter/plugins/ reference page may still mention only JS/CSS - the blog is authoritative). Profile rule and plugin execution with biome lint --profile-rules..

Suppression Patterns

Single-line

// biome-ignore lint/suspicious/noConsole: needed for debugging
console.log("debug info");

File-level

// biome-ignore-all lint/suspicious/noConsole: logger module

Range

// biome-ignore-start lint/style/useConst: legacy code
let x = 1;
let y = 2;
// biome-ignore-end lint/style/useConst
const a = 4; // this line IS checked

biome-ignore-end is optional - omit to suppress until end of file. Biome requires explanation text after the colon.

Migration

From ESLint

pnpm biome migrate eslint --write
pnpm biome migrate eslint --write --include-inspired  # Include non-identical rules

Supports legacy and flat configs, extends resolution, plugins (typescript-eslint, react, jsx-a11y, unicorn), .eslintignore.

From Prettier

pnpm biome migrate prettier --write

Maps tabWidth -> indentWidth, useTabs -> indentStyle, singleQuote -> quoteStyle, trailingComma -> trailingCommas.

From ESLint + Prettier combo

pnpm biome migrate eslint --write
pnpm biome migrate prettier --write
pnpm remove eslint prettier eslint-config-prettier eslint-plugin-prettier \
  @typescript-eslint/parser @typescript-eslint/eslint-plugin
rm .eslintrc* .prettierrc* .eslintignore .prettierignore

Enable VCS integration since ESLint respects gitignore by default:

{ "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true } }

CLI Reference

biome check (primary command)

biome check .                    # Check all files
biome check --write .            # Apply safe fixes
biome check --write --unsafe .   # Apply all fixes
biome check --changed .          # Only VCS-changed files
biome check --staged .           # Only staged files

biome ci (CI mode)

biome ci .                                           # No writes, exit code on errors
biome ci --reporter=github .                         # GitHub annotations
biome ci --reporter=sarif --reporter-file=report.sarif .  # SARIF output

biome lint

biome lint --only=suspicious/noDebugger .    # Single rule
biome lint --skip=project .                  # Skip domain
biome lint --only=types .                    # Only type-aware rules
biome lint --error-on-warnings .             # Warnings become errors
biome lint --enforce-assist .                # Fail when assist actions remain unapplied
biome lint --suppress --reason "tracked in #123" .  # Insert biome-ignore suppressions instead of fixes

--enforce-assist is useful in CI: import organization and other assist actions aren't lint diagnostics by default, so plain biome ci may pass even when imports are unsorted. Pair --suppress with --reason to bulk-add biome-ignore comments (Biome requires explanation text after the colon).

Other commands

biome format --write .                       # Format only
biome search '`console.$method($args)`' .    # GritQL pattern search
biome rage                                   # Debug info for bug reports
biome explain noFloatingPromises             # Explain a rule

Best Practices

1. Use biome check as your single command - combines format, lint, and import organization
2. Start with recommended: true - disable individual rules as needed
3. Enable relevant domains - react, next, test, types based on your stack
4. Enable VCS integration - respects .gitignore, enables --changed/--staged
5. Use biome ci in pipelines - never writes files, clear exit codes
6. Pin exact versions - avoid surprise rule changes between releases
7. Run biome migrate --write after every upgrade
8. Use --staged in pre-commit hooks: biome check --staged --write --no-errors-on-unmatched.
9. Profile slow rules with biome lint --profile-rules (v2.4)
10. Use GritQL plugins for project-specific patterns instead of disabling rules globally

Gotchas

These are real mistakes that have caused broken configs, dirty working trees, and wasted debugging time. Read before writing any Biome config.

1. files.ignore, files.include, files.exclude do not exist. Only files.includes (with s). Biome will throw Found an unknown key for anything else. See the first critical rule above.
2. organizeImports is NOT a top-level config key. In Biome 2.x it moved under assist.actions.source.organizeImports. Using it at the top level is a config error.
3. overrides that disable linter + formatter still run assist. If you use overrides to skip a generated file, the import organizer (an assist action) will still rewrite it. This silently dirties your working tree. Use files.includes negation to fully exclude a file instead.
4. overrides field is includes (with s), not include. Same naming as files.includes.
5. biome check --write runs formatter + linter + assists in one pass. Any of these three can modify files. If a generated file keeps getting dirtied after check --write, check which subsystem is touching it - it's often the import organizer (assist), not the formatter or linter.
6. Prefer --write over --fix. --fix is a documented alias for --write on biome lint and biome format, but biome check is the canonical entry point and --write is the documented flag everywhere. Pick --write and be consistent.
7. package.json infinite reformatting loop. Biome's default JSON formatter uses tabs; pnpm (and several other tools) write package.json with 2-space indent. Each install rewrites it, then biome check --write rewrites it again, dirtying every commit. Fix by either excluding package.json ("!**/package.json" in files.includes) or overriding JSON to use spaces: {"overrides": [{"includes": ["**/package.json"], "json": {"formatter": {"indentStyle": "space", "indentWidth": 2}}}]}

Resources

• Biome Docs: https://biomejs.dev/
• Biome GitHub: https://github.com/biomejs/biome
• GritQL Docs: https://docs.grit.io/
• Biome v2 Blog: https://biomejs.dev/blog/biome-v2/
• Biome v2.4 Blog: https://biomejs.dev/blog/biome-v2-4/
• Migration Guide: https://biomejs.dev/guides/migrate-eslint-prettier/
• Rules Reference: https://biomejs.dev/linter/javascript/rules/
• Domains: https://biomejs.dev/linter/domains/
• Plugins: https://biomejs.dev/linter/plugins/

For detailed lint rules by category with code examples, see rules-reference.md.