biome-v2

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

Rule	Group	Default	Description
noExplicitAny	suspicious	off	Disallow any type
useImportType	style	off	Promote import type for types
noUnusedImports	correctness	error	Remove unused imports
noUnusedVariables	correctness	error	Detect unused variables
noNonNullAssertion	style	warn	Discourage ! operator
useConst	style	warn	Prefer const over let
noForEach	complexity	warn	Prefer for-of over .forEach()

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" }
    }
  }
}