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:

• Install Biome as dev dependency

• Run npx @biomejs/biome init

• Configure biome.json for project needs

• Add scripts to package.json

• Set up editor integration

• 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:

• Audit existing ESLint/Prettier config

• Map rules to Biome equivalents

• Configure Biome to match existing style

• Run side-by-side comparison

• Remove ESLint/Prettier dependencies

• 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:

• Create root biome.json with shared config

• Use extends in package-specific configs

• Configure file patterns for each package

• Set up workspace-aware linting

• 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

• Start with recommended rules - Enable "recommended": true then customize

• Use VCS integration - Let Biome respect .gitignore

• Pin Biome version - Use exact versions in package.json

• Configure per-language - Override general settings for specific languages

• Use overrides sparingly - Prefer consistent configuration across the project

• Test before committing - Run biome ci in CI/CD

• Enable editor integration - Format on save for best experience

• 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.