Biome

Biome - Professional TypeScript/JavaScript Tooling

Biome is a fast, modern toolchain for JavaScript, TypeScript, JSX, JSON, CSS, GraphQL, and HTML. It provides formatting, linting, and code analysis with a single tool and zero configuration required.

When to Use This Skill

Use this skill when:

• Setting up Biome in a new or existing project
• Configuring biome.json for specific requirements
• Migrating from ESLint and/or Prettier to Biome
• Implementing linter rules or formatter options
• Integrating Biome with editors (VS Code, Zed, IntelliJ)
• Setting up CI/CD pipelines with Biome
• Configuring monorepos or large projects
• Debugging Biome configuration or performance issues
• Understanding specific lint rules or code actions
• Upgrading from Biome v1 to v2

Quick Start

Installation

# npm
npm i -D -E @biomejs/biome

# pnpm
pnpm add -D -E @biomejs/biome

# yarn
yarn add -D -E @biomejs/biome

Initialize Configuration

npx @biomejs/biome init

This creates a biome.json with recommended defaults.

Basic Commands

# Format and lint
npx @biomejs/biome check --write ./src

# Format only
npx @biomejs/biome format --write ./src

# Lint only
npx @biomejs/biome lint ./src

# CI mode (no writes, exit on errors)
npx @biomejs/biome ci ./src

Core Workflows

1. Project Setup

For new projects:

1. Install Biome as dev dependency
2. Run npx @biomejs/biome init
3. Configure biome.json for project needs
4. Add scripts to package.json
5. Set up editor integration
6. Configure CI/CD

See references/docs/guides/getting-started.md for details.

2. Configuration

Biome configuration lives in biome.json or biome.jsonc. Key sections:

• $schema - JSON schema for IDE autocomplete
• files - File inclusion/exclusion patterns
• formatter - Formatting options (indentation, line width, etc.)
• linter - Linting rules and their configuration
• javascript, json, css - Language-specific options
• overrides - Per-file or per-directory overrides

For complete configuration reference, see references/docs/reference/configuration.md.

3. Migration from ESLint/Prettier

Biome can replace both ESLint and Prettier in most projects:

1. Audit existing ESLint/Prettier config
2. Map rules to Biome equivalents
3. Configure Biome to match existing style
4. Run side-by-side comparison
5. Remove ESLint/Prettier dependencies
6. Update scripts and CI/CD

See references/docs/guides/migrate-eslint-prettier.md for detailed migration guide.

4. Monorepo/Large Projects

For monorepos or projects with multiple packages:

1. Create root biome.json with shared config
2. Use extends in package-specific configs
3. Configure file patterns for each package
4. Set up workspace-aware linting
5. Optimize for performance

See references/docs/guides/big-projects.md for monorepo patterns.

5. Editor Integration

Biome has official extensions for:

• VS Code - Full LSP support, format on save, quick fixes
• Zed - Native integration, inline diagnostics
• IntelliJ - Plugin available

Install the extension for your editor and configure workspace settings. See references/docs/guides/editors_first-party-extensions.md.

Reference Documentation

This skill includes complete Biome v2.x documentation:

Essential References

• INDEX.md - Complete documentation index
• CLI Reference - All commands and options (70 KB)
• Configuration Reference - All config options (42 KB)
• JavaScript Rules - Complete rule list (68 KB)

Documentation Categories

Guides (11 files)

• Getting started, configuration, migration, editor setup, monorepos

Formatter (3 files)

• Formatting engine, Prettier differences, design philosophy

Linter (13 files)

• Linting rules for JavaScript/TypeScript, CSS, JSON, GraphQL, HTML
• Rule sources and framework-specific domains (React, Next.js, etc.)

Assist (9 files)

• Code actions and refactoring capabilities for all languages

Reference (8 files)

• CLI, configuration, diagnostics, environment variables, reporters, editor extensions

Recipes (4 files)

• CI/CD integration, git hooks, Renovate setup, badges

Internals (7 files)

• Architecture, philosophy, language support, versioning, changelogs

Use references/INDEX.md for quick navigation to specific topics.

Common Patterns

Typical biome.json

{
  "$schema": "https://biomejs.dev/schemas/2.0.5/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false,
    "includes": ["src/**/*"]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  }
}

Package.json Scripts

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

CI/CD Integration

# GitHub Actions
- name: Run Biome
  run: npx @biomejs/biome ci .

See references/docs/recipes/continuous-integration.md for complete CI/CD examples.

Updating Documentation

To update this skill's documentation with the latest from biomejs.dev:

python scripts/scrape_biome_docs.py --update-all --output references/docs

This scrapes all current documentation and updates the reference files.

Key Concepts

Formatting Philosophy

• Opinionated defaults with minimal configuration
• Focuses on consistency over personal preference
• Significantly faster than Prettier (10-20x)
• Format-preserving when possible

Linting Approach

• Rules organized by category (correctness, performance, style, etc.)
• Framework-aware domains (React, Next.js, etc.)
• Recommended rules enabled by default
• Fast incremental linting

Tool Integration

• Single tool replaces ESLint + Prettier + more
• Zero-config defaults work for most projects
• Native TypeScript support, no type-checking required
• Incremental adoption possible

Best Practices

1. Start with recommended rules - Enable "recommended": true then customize
2. Use VCS integration - Let Biome respect .gitignore
3. Pin Biome version - Use exact versions in package.json
4. Configure per-language - Override general settings for specific languages
5. Use overrides sparingly - Prefer consistent configuration across the project
6. Test before committing - Run biome ci in CI/CD
7. Enable editor integration - Format on save for best experience
8. Read diagnostics carefully - Biome provides detailed error explanations

Troubleshooting

Common issues and solutions:

Biome not finding files

• Check files.includes in biome.json
• Verify VCS integration settings
• Review .gitignore patterns

Performance issues

• See references/docs/guides/investigate-slowness.md
• Check file inclusion patterns
• Consider using files.ignoreUnknown

Rule conflicts with existing code

• Use suppressions for one-off cases
• Configure rule severity (error/warn/off)
• See references/docs/analyzer/suppressions.md

Migration issues

• Compare Biome output with ESLint/Prettier
• Use configuration overrides for edge cases
• See migration guide for common patterns

For detailed troubleshooting, consult the relevant reference documentation.

Resources

scripts/

Contains the Biome documentation scraper for keeping this skill up to date:

• scrape_biome_docs.py - Scrapes and cleans Biome documentation from biomejs.dev

references/

Complete Biome v2.x documentation (56 files, 896 KB):

• INDEX.md - Navigation index for all documentation
• docs/ - All scraped and cleaned documentation files organized by category

The documentation is comprehensive and production-ready, covering all aspects of Biome from installation to advanced usage patterns.