name: biome-v2 description: > Biome v2 linter/formatter reference. Auto-loads when working with biome.json, biome config, linting rules, formatting, import organization, biome check. user-invocable: false

Biome Reference

Version: 2.x Docs: https://biomejs.dev/

CLI Commands

# Check (format + lint + organize imports)
biome check .               # Read-only check
biome check --write .       # Apply safe fixes + formatting
biome check --unsafe .      # Apply unsafe fixes (requires --write)

# Lint only
biome lint ./src
biome lint --write ./src    # Apply safe fixes

# Format only
biome format --write ./src

# CI mode (read-only, optimized output)
biome ci ./src

# VCS-based filtering
biome check --staged        # Only staged files
biome check --changed       # Changed vs default branch
biome check --since=origin/develop

# Migrate from ESLint/Prettier
biome migrate eslint --write
biome migrate prettier --write

Configuration (biome.json)

Formatter

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",      // "tab" | "space"
    "indentWidth": 2,
    "lineWidth": 120,
    "lineEnding": "lf",
    "bracketSpacing": true
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",    // "single" | "double"
      "semicolons": "always",    // "always" | "asNeeded"
      "trailingCommas": "es5"    // "all" | "es5" | "none"
    }
  }
}

Linter

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "error"
      },
      "style": {
        "useImportType": "error",
        "noNonNullAssertion": "warn"
      },
      "correctness": {
        "noUnusedImports": "error",
        "noUnusedVariables": "error"
      }
    }
  }
}

Rule severity levels: "off" | "warn" | "error" | "info"

Rule groups:

• accessibility — A11y checks
• complexity — Overly complex code
• correctness — Guaranteed incorrect/useless code
• performance — Efficiency improvements
• security — Vulnerabilities
• style — Code style consistency
• suspicious — Likely incorrect patterns

VCS Integration

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

Import Organization

{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

Overrides

Apply different settings to specific file patterns:

{
  "overrides": [
    {
      "includes": ["**/__tests__/**", "**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": { "noExplicitAny": "off" }
        }
      }
    }
  ]
}

Files

{
  "files": {
    "includes": ["**", "!**/node_modules", "!**/dist"],
    "maxSize": 1048576
  }
}

Glob patterns:

• * — Files only (not directories)
• ** — Recursive
• !pattern — Exclude
• !!pattern — Force-ignore (prevents indexing)

Common Rules

Inline Suppressions

// biome-ignore lint/suspicious/noExplicitAny: legacy code
function legacyFunction(data: any) {}

// biome-ignore lint/suspicious/noExplicitAny lint/style/useConst: testing
let testVar: any = 'test';

VS Code Integration

Install extension: biomejs.biome

.vscode/settings.json:

{
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

Gotchas & Version Caveats

Default indentation is tabs, not spaces — Override with indentStyle: "space" if needed.

Default quotes are double, not single — Override with quoteStyle: "single".

97% Prettier compatibility — Some edge cases format differently. Not a drop-in replacement.

VCS integration required for .gitignore — Enable vcs.enabled: true to respect .gitignore (not enabled by default).

node_modules always ignored — Even if not in files.ignoreUnknown.

--write required for fixes — biome check without --write is read-only.

--unsafe requires --write — Cannot apply unsafe fixes without write mode.

Rule configuration object vs severity — Rules accept either a string ("error") or object ({ "level": "error", "options": {} }).

Overrides apply in order — Later overrides win. Be careful with order-dependent config.

Migration overwrites biome.json — Commit before running biome migrate.

Type-aware linting in v2 — Doesn't rely on TypeScript compiler (unlike ESLint).

Install with --save-exact — Avoid unexpected breaking changes across minor versions.

Anti-Patterns

Bad: Ignoring VCS integration

{
  "vcs": { "enabled": false }
}

Good: Enable VCS

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

Bad: Running format and lint separately

biome format --write .
biome lint --write .

Good: Use check (faster, combines all checks)

biome check --write .

Bad: Allowing any everywhere

{
  "linter": {
    "rules": {
      "suspicious": { "noExplicitAny": "off" }
    }
  }
}

Good: Allow in tests only via overrides

{
  "overrides": [{
    "includes": ["**/__tests__/**"],
    "linter": {
      "rules": {
        "suspicious": { "noExplicitAny": "off" }
      }
    }
  }]
}

Bad: Disabling noUnusedImports

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

Good: Keep enabled, let Biome clean up

{
  "linter": {
    "rules": {
      "correctness": { "noUnusedImports": "error" }
    }
  }
}