Biome Configuration

Master Biome configuration including biome.json setup, schema versions, VCS integration, and project organization for optimal JavaScript/TypeScript tooling.

Overview

Biome is a fast, modern toolchain for JavaScript and TypeScript projects that combines linting and formatting in a single tool. It's designed as a performant alternative to ESLint and Prettier, written in Rust for maximum speed.

Installation and Setup

Basic Installation

Install Biome in your project:

npm install --save-dev @biomejs/biome

or

pnpm add -D @biomejs/biome

or

yarn add -D @biomejs/biome

Initialize Configuration

Create a basic biome.json configuration:

npx biome init

This creates a biome.json file in your project root.

Configuration File Structure

Basic biome.json

{ "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true }, "files": { "ignoreUnknown": false, "ignore": [] }, "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2, "lineWidth": 80 }, "linter": { "enabled": true, "rules": { "recommended": true } }, "javascript": { "formatter": { "quoteStyle": "single", "trailingCommas": "es5" } } }

Schema Versioning

Always use the correct schema version matching your Biome installation:

Check Biome version

npx biome --version

Migrate configuration to current version

npx biome migrate --write

The $schema field enables IDE autocomplete and validation:

{ "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json" }

VCS Integration

Configure version control integration to respect .gitignore:

{ "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" } }

Options:

• enabled : Enable VCS integration

• clientKind : "git" for Git repositories

• useIgnoreFile : Respect .gitignore patterns

• defaultBranch : Default branch name for operations

File Management

File Patterns

Control which files Biome processes:

{ "files": { "ignoreUnknown": false, "ignore": [ "/node_modules/", "/dist/", "/.next/", "/build/", "/.cache/" ], "include": ["src//*.ts", "src//*.tsx"] } }

Common Ignore Patterns

{ "files": { "ignore": [ "/node_modules/", "/dist/", "/build/", "/.next/", "/.cache/", "/coverage/", "/*.min.js", "/*.log" ] } }

Formatter Configuration

Basic Formatter Settings

{ "formatter": { "enabled": true, "formatWithErrors": false, "indentStyle": "space", "indentWidth": 2, "lineEnding": "lf", "lineWidth": 80 } }

Options:

• enabled : Enable/disable formatter

• formatWithErrors : Format even with syntax errors

• indentStyle : "space" or "tab"

• indentWidth : Number of spaces (2 or 4 recommended)

• lineEnding : "lf", "crlf", or "cr"

• lineWidth : Maximum line length

Language-Specific Formatting

JavaScript/TypeScript

{ "javascript": { "formatter": { "quoteStyle": "single", "quoteProperties": "asNeeded", "trailingCommas": "all", "semicolons": "always", "arrowParentheses": "always", "bracketSpacing": true, "bracketSameLine": false } } }

JSON

{ "json": { "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2, "lineWidth": 80, "trailingCommas": "none" } } }

Linter Configuration

Enable Recommended Rules

{ "linter": { "enabled": true, "rules": { "recommended": true } } }

Rule Categories

Configure specific rule groups:

{ "linter": { "enabled": true, "rules": { "recommended": true, "a11y": { "recommended": true }, "complexity": { "recommended": true }, "correctness": { "recommended": true }, "performance": { "recommended": true }, "security": { "recommended": true }, "style": { "recommended": true }, "suspicious": { "recommended": true } } } }

Fine-Grained Rule Control

Enable or disable specific rules:

{ "linter": { "rules": { "recommended": true, "suspicious": { "noExplicitAny": "error", "noConsoleLog": "warn" }, "style": { "useConst": "error", "noVar": "error" } } } }

Rule levels:

• "off" : Disable rule

• "warn" : Show warning

• "error" : Fail check

Monorepo Configuration

Root Configuration

{ "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json", "extends": [], "files": { "ignore": ["/node_modules/", "/dist/"] }, "formatter": { "enabled": true, "indentWidth": 2 }, "linter": { "enabled": true, "rules": { "recommended": true } } }

Package-Specific Overrides

Each package can have its own biome.json:

{ "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json", "extends": ["../../biome.json"], "linter": { "rules": { "suspicious": { "noConsoleLog": "off" } } } }

Best Practices

• Use Schema URLs - Always include $schema for IDE support

• Version Management - Run biome migrate after updates

• VCS Integration - Enable VCS to respect .gitignore

• Consistent Formatting - Set clear formatter rules across team

• Rule Documentation - Document why specific rules are disabled

• Monorepo Strategy - Use extends for shared configuration

• CI Integration - Run biome ci in continuous integration

• Pre-commit Hooks - Validate code before commits

• Editor Integration - Install Biome VSCode/IDE extensions

• Regular Updates - Keep Biome updated for new features

Common Pitfalls

• Schema Mismatch - Using outdated schema version

• Missing Migration - Not running migrate after updates

• Overly Strict - Enabling all rules without team agreement

• No VCS Integration - Not respecting gitignore patterns

• Inconsistent Config - Different settings across packages

• Ignored Warnings - Dismissing warnings that indicate issues

• No Editor Setup - Missing IDE integration for real-time feedback

• Large Line Width - Setting lineWidth too high reduces readability

• Mixed Quotes - Not enforcing consistent quote style

• No CI Enforcement - Not running checks in CI pipeline

Advanced Topics

Overrides Per Path

{ "overrides": [ { "include": ["scripts//*.js"], "linter": { "rules": { "suspicious": { "noConsoleLog": "off" } } } }, { "include": ["/*.test.ts"], "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } } } ] }

Custom Scripts

Add to package.json:

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

CI/CD Integration

CI mode (fails on warnings)

biome ci .

Check without fixing

biome check .

Fix automatically

biome check --write .

Format only

biome format --write .

When to Use This Skill

• Setting up Biome in new projects

• Migrating from ESLint/Prettier to Biome

• Configuring Biome for monorepos

• Customizing linting and formatting rules

• Troubleshooting Biome configuration issues

• Integrating Biome with CI/CD pipelines

• Establishing team code standards

• Optimizing Biome performance

Troubleshooting

Schema Version Mismatch

Error: Schema version doesn't match CLI version

npx biome migrate --write

Files Not Being Checked

Check:

• VCS integration and .gitignore

• files.ignore patterns

• files.include if specified

• File extensions supported by Biome

Rules Not Applying

Verify:

• linter.enabled is true

• Rule category is enabled

• Rule name is correct

• No overrides disabling the rule

Performance Issues

Optimize:

• Use files.ignore for large directories

• Enable VCS integration

• Exclude generated files

• Update to latest Biome version