Biome Configuration

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: biome for comprehensive documentation.

When NOT to Use This Skill

This skill is specific to Biome tooling. Do NOT use for:

• ESLint configuration - Biome replaces ESLint; migrate or use ESLint skills
• Prettier configuration - Biome replaces Prettier; migrate or use Prettier docs
• TypeScript type checking - Use tsc, not Biome (Biome doesn't type check)
• Build process - Use bundler skills (Vite, Webpack, etc.)
• Testing setup - Use testing framework skills (Vitest, Jest, etc.)
• Code quality principles - Use clean-code skill for what to fix, not how to configure

Anti-Patterns

Anti-Pattern	Why It's Bad	Biome Best Practice
Disabling recommended rules	Misses important issues	Keep recommended, customize only what's needed
Ignoring all warnings	Warnings indicate real issues	Fix warnings or suppress with reason
No CI integration	Issues slip through	Use biome ci in CI pipeline
Manual formatting	Inconsistent, waste time	Use format on save + pre-commit hooks
Mixing ESLint + Biome	Conflicting rules, confusion	Fully migrate to Biome or stay with ESLint
No VS Code integration	Manual CLI runs	Install Biome extension, enable format on save
Ignoring complexity rules	Allows unmaintainable code	Set cognitive complexity limits
Committing formatting issues	Messy diffs	Use pre-commit hooks with lint-staged

Quick Troubleshooting

Issue	Check	Solution
Biome not formatting	VS Code extension installed?	Install biomejs.biome, set as default formatter
Format on save not working	Settings.json configured?	Add "editor.formatOnSave": true
Rules not applying	biome.json syntax valid?	Run biome check to validate config
Too many warnings	Rules too strict?	Adjust severity levels or disable specific rules
CI failing	Different results locally?	Ensure same Biome version, check ignore patterns
Conflicts with Prettier	Both running?	Remove Prettier, Biome replaces it
Slow on large codebase	Checking too many files?	Add ignore patterns in biome.json
Can't migrate from ESLint	Complex config?	Use biome migrate eslint, review output

Installation

npm install --save-dev @biomejs/biome

# Initialize configuration
npx @biomejs/biome init

biome.json Configuration

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": {
            "maxAllowedComplexity": 15
          }
        }
      },
      "correctness": {
        "noUnusedVariables": "warn",
        "noUnusedImports": "warn",
        "useExhaustiveDependencies": "warn"
      },
      "style": {
        "noNonNullAssertion": "off",
        "useImportType": "warn"
      },
      "suspicious": {
        "noExplicitAny": "warn"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  },
  "files": {
    "ignore": [
      "node_modules",
      "dist",
      "build",
      ".next",
      "coverage",
      "*.gen.ts"
    ]
  }
}

Package.json Scripts

{
  "scripts": {
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "format": "biome format --write .",
    "check": "biome check --write --unsafe ."
  }
}

Common Rules

Rule	Level	Description
noUnusedVariables	warn	Flag unused variables
noUnusedImports	warn	Flag unused imports
noExplicitAny	warn	Discourage any type
useExhaustiveDependencies	warn	Check React hook deps
noNonNullAssertion	off	Allow ! operator
useImportType	warn	Prefer import type

VS Code Integration

// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

Pre-commit Hook

# Install husky
npm install --save-dev husky lint-staged

# package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

Migration from ESLint/Prettier

# Biome can migrate your config
npx @biomejs/biome migrate eslint --write
npx @biomejs/biome migrate prettier --write

CLI Commands

# Check all files
biome check .

# Fix issues
biome check --write .

# Format only
biome format --write .

# Lint only
biome lint .

# Check specific files
biome check src/components/**/*.tsx

# CI mode (exit with error)
biome ci .

Ignoring Code

// Ignore next line
// biome-ignore lint/suspicious/noExplicitAny: needed for legacy API
const data: any = await fetch('/api');

// Ignore whole file (at top)
// biome-ignore-all lint/style/useImportType

Production Readiness

Recommended Configuration

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "a11y": {
        "recommended": true
      },
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "error",
          "options": { "maxAllowedComplexity": 15 }
        },
        "noExcessiveNestedTestSuites": "warn"
      },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error",
        "useExhaustiveDependencies": "error"
      },
      "performance": {
        "noAccumulatingSpread": "warn",
        "noDelete": "warn"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error",
        "noGlobalEval": "error"
      },
      "suspicious": {
        "noExplicitAny": "warn",
        "noConsoleLog": "warn"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  },
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  }
}

CI Integration

# .github/workflows/lint.yml
name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Biome CI
        run: npx @biomejs/biome ci .

      # Or with caching
      - name: Cache Biome
        uses: actions/cache@v4
        with:
          path: ~/.cache/biome
          key: ${{ runner.os }}-biome-${{ hashFiles('biome.json') }}

      - name: Check
        run: npx @biomejs/biome check --diagnostic-level=error .

Git Hooks

// package.json
{
  "scripts": {
    "prepare": "husky install",
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "lint:ci": "biome ci ."
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json}": [
      "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
    ]
  }
}

# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

Error Handling

// biome.json - Configure severity levels
{
  "linter": {
    "rules": {
      // Block CI on these
      "correctness": {
        "noUnusedVariables": "error",
        "useExhaustiveDependencies": "error"
      },
      // Allow in development, fail in CI
      "suspicious": {
        "noConsoleLog": {
          "level": "warn",
          "options": {}
        }
      }
    }
  }
}

// Stricter CI check
// package.json
{
  "scripts": {
    "lint:dev": "biome check .",
    "lint:ci": "biome check --diagnostic-level=error --max-diagnostics=50 ."
  }
}

Testing Integration

// vitest.config.ts - Run biome before tests
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globalSetup: './src/test/global-setup.ts',
  },
});

// src/test/global-setup.ts
import { execSync } from 'child_process';

export default function setup() {
  try {
    execSync('npx @biomejs/biome check .', { stdio: 'pipe' });
  } catch (error) {
    console.error('Biome check failed. Fix linting issues before running tests.');
    process.exit(1);
  }
}

Monitoring Metrics

Metric	Target
Lint errors	0
Warnings	< 10
Format issues	0
Cognitive complexity	< 15

Checklist

• Recommended rules enabled
• Security rules enabled
• a11y rules enabled
• Cognitive complexity limit
• CI integration with biome ci
• Pre-commit hooks with lint-staged
• VS Code extension configured
• Console.log warnings
• Unused variables as errors
• VCS integration enabled

Reference Documentation

• Rules Reference
• VS Code Setup