d-subrahmanyam/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

| 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