Biome

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

Quick Troubleshooting

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

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

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