Configuring Biome: Rules, Formatter Options, and Per-Glob Overrides in biome.json

The problem: one config file to rule them all

Biome replaces ESLint, Prettier, and their assorted config files with a single biome.json (or biome.jsonc) at the project root. That file controls formatting, linting, and code assists for JavaScript, TypeScript, JSX, TSX, JSON, and CSS. The useful takeaway: you define rule severities, formatter preferences, and directory-specific exceptions in one place, then run biome check --apply to enforce them. This article walks through a practical configuration, shows where the knobs live, and highlights the limits you’ll hit in current stable releases.

Minimal working configuration

Create biome.json at the repository root. The $schema key enables autocomplete in VS Code and other editors that support JSON Schema.

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "quoteStyle": "single"
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "style": {
        "useConst": "error",
        "noUnusedTemplateLiteral": "warn"
      },
      "correctness": {
        "noUnusedVariables": "error"
      },
      "suspicious": {
        "noExplicitAny": "warn"
      }
    }
  },
  "overrides": [
    {
      "includes": ["**/*.test.ts", "**/*.spec.ts"],
      "linter": {
        "rules": {
          "style": {
            "useConst": "off"
          }
        }
      }
    },
    {
      "includes": ["generated/**"],
      "linter": {
        "enabled": false
      },
      "formatter": {
        "enabled": false
      }
    }
  ]
}

Run biome check --apply from the repository root (no elevated permissions needed) to lint and format in one pass. Run biome format --write if you only want formatting. Both commands read this file automatically.

How the configuration works

Rule domains and severity

Rules live under linter.rules grouped by domain: recommended, correctness, style, suspicious, complexity, performance, security, and nursery. Each rule accepts "off", "warn", or "error". Setting "recommended": true enables the curated default set at error severity; you then override individual rules as shown above. The nursery domain contains experimental rules that may be promoted, renamed, or removed in minor releases — treat them as unstable.

Formatter options

The formatter key holds options that apply uniformly across all supported languages. There is no per-language formatter config in current stable releases. Common options:

• indentStyle: "tab" | "space"
• indentWidth: number (ignored when indentStyle is "tab")
• lineWidth: number (affects JS, TS, JSON, CSS alike)
• quoteStyle: "single" | "double"

Unknown keys or invalid values cause a clear startup error with the offending JSON path, preventing silent misconfiguration.

Per-glob overrides

The overrides array lets you relax or disable rules for specific file patterns. Entries are evaluated in order; later entries can shadow earlier ones if globs overlap. In the example above, test files get useConst turned off, while everything under generated/ skips both linting and formatting entirely. Test the effective config for a given file with:

biome check --config-path=biome.json --files=src/utils/helper.test.ts

This prints the resolved rule set for that file, letting you verify override precedence before committing.

Limits and common mistakes

No per-rule thresholds

Biome does not yet support per-rule configuration options such as a max-len threshold. Rules with fixed thresholds (e.g., line length in certain complexity rules) cannot be tuned — only toggled between off, warn, and error.

Formatter options are global

lineWidth, indentWidth, and other formatter settings apply to every language Biome formats. If your CSS needs a different line width than your TypeScript, you cannot express that today. Workaround: run a separate formatter for the outlier language, or accept the shared setting.

Override ordering matters

Because overrides apply sequentially, a broad glob placed after a narrow one can unintentionally reset the narrow one’s settings. Keep the array ordered from most specific to least specific, and verify with the --files check shown above.

JSONC comments do not survive formatting

You can write biome.jsonc with comments for documentation, but biome format --write biome.jsonc strips them. Keep a separate biome.jsonc for editing and a generated biome.json for CI if you need comments in source control.

Schema version pinning

The $schema URL includes a version (e.g., 1.9.4). Update it when you upgrade Biome to get accurate autocomplete for new rules and options. The schema is published at https://biomejs.dev/schemas/<version>/schema.json.

Verification checklist

1. Add $schema and open biome.json in VS Code — autocomplete should suggest rule names and formatter keys.
2. Run biome check --apply on a test file that violates useConst; confirm it reports an error and fixes it on --apply.
3. Run biome check --config-path=biome.json --files=**/*.test.ts and verify useConst is reported as off for those files.
4. If migrating from ESLint, run biome migrate eslint --write to generate a starter config, then diff against your hand-written version to understand the mapping.

Rollback note

biome check --apply and biome format --write modify source files. Commit or stash changes before running them so you can revert with git checkout -- . if the results are unexpected. The configuration file itself does not change state; editing it requires no rollback beyond version control.