Biome - Fast All-in-One Toolchain

Overview

Biome is a fast, all-in-one toolchain for web projects written in Rust. It replaces both ESLint and Prettier with a single tool that's 100x faster and provides zero-config defaults.

Key Features:

• Single tool for linting and formatting

• 100x faster than ESLint

• Zero configuration by default

• Built-in import sorting

• TypeScript-first design

• Partial Prettier compatibility

• Native monorepo support

• VS Code integration

Installation:

npm install --save-dev @biomejs/biome

Quick Start

1. Initialize Biome

Create biome.json configuration

npx @biomejs/biome init

Check your project

npx @biomejs/biome check .

Fix issues automatically

npx @biomejs/biome check --write .

Format only

npx @biomejs/biome format --write .

Lint only

npx @biomejs/biome lint .

2. Package.json Scripts

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

3. Basic Configuration

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

Core Commands

Check Command (Recommended)

The check command runs both linting and formatting:

Check all files

biome check .

Fix issues automatically

biome check --write .

Unsafe fixes (may change behavior)

biome check --write --unsafe .

Apply suggested fixes

biome check --write --unsafe --apply-suggested

Check specific files

biome check src/**/*.ts

CI mode (exit with error on issues)

biome ci .

Format Command

Format code without linting:

Format all files

biome format --write .

Check formatting without changing files

biome format .

Format specific files

biome format --write src/**/*.{ts,tsx,js,jsx}

Format stdin

echo "const x={a:1}" | biome format --stdin-file-path=file.js

Lint Command

Lint code without formatting:

Lint all files

biome lint .

Fix linting issues

biome lint --write .

Show rule names

biome lint --verbose .

Apply unsafe fixes

biome lint --write --unsafe .

Configuration Deep Dive

Formatter Configuration

{ "formatter": { "enabled": true, "formatWithErrors": false, "indentStyle": "space", "indentWidth": 2, "lineEnding": "lf", "lineWidth": 80, "attributePosition": "auto" }, "javascript": { "formatter": { "quoteStyle": "single", "jsxQuoteStyle": "double", "quoteProperties": "asNeeded", "trailingCommas": "all", "semicolons": "asNeeded", "arrowParentheses": "always", "bracketSpacing": true, "bracketSameLine": false } }, "json": { "formatter": { "trailingCommas": "none" } } }

Linter Configuration

{ "linter": { "enabled": true, "rules": { "recommended": true, "a11y": { "recommended": true, "noAutofocus": "error", "useKeyWithClickEvents": "warn" }, "complexity": { "recommended": true, "noForEach": "off", "useLiteralKeys": "error" }, "correctness": { "recommended": true, "noUnusedVariables": "error", "useExhaustiveDependencies": "warn" }, "performance": { "recommended": true, "noAccumulatingSpread": "warn" }, "security": { "recommended": true, "noDangerouslySetInnerHtml": "error" }, "style": { "recommended": true, "noNonNullAssertion": "warn", "useConst": "error", "useTemplate": "warn" }, "suspicious": { "recommended": true, "noExplicitAny": "warn", "noArrayIndexKey": "error" } } } }

File Ignore Patterns

{ "files": { "ignore": [ "node_modules", "dist", "build", ".next", "coverage", ".min.js", "public/assets/" ], "ignoreUnknown": false, "include": ["src//.ts", "src/**/*.tsx"] } }

Override Configuration for Specific Files

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

VS Code Integration

1. Install Biome Extension

Install from VS Code marketplace

code --install-extension biomejs.biome

2. VS Code Settings (.vscode/settings.json )

{ "[javascript]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "quickfix.biome": "explicit", "source.organizeImports.biome": "explicit" } }, "[typescript]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "quickfix.biome": "explicit", "source.organizeImports.biome": "explicit" } }, "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true }, "[json]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true }, "biome.lspBin": "./node_modules/@biomejs/biome/bin/biome" }

3. Workspace Settings

{ "editor.formatOnSave": true, "editor.formatOnPaste": true, "editor.defaultFormatter": "biomejs.biome", "biome.rename": true, "files.autoSave": "onFocusChange" }

Migration from ESLint and Prettier

1. Remove Old Tools

Remove ESLint and Prettier

npm uninstall eslint prettier eslint-config-prettier
eslint-plugin-react eslint-plugin-import
@typescript-eslint/parser @typescript-eslint/eslint-plugin

Remove configuration files

rm .eslintrc.js .eslintrc.json .prettierrc .prettierignore

2. Migrate Configuration

Use Biome's migration tool:

Migrate from Prettier config

biome migrate prettier --write

Migrate from ESLint config

biome migrate eslint --write

3. Manual Migration

Prettier → Biome Formatter:

// .prettierrc (old) { "semi": false, "singleQuote": true, "trailingComma": "all", "printWidth": 100 }

// biome.json (new) { "formatter": { "lineWidth": 100 }, "javascript": { "formatter": { "semicolons": "asNeeded", "quoteStyle": "single", "trailingCommas": "all" } } }

ESLint → Biome Linter:

// .eslintrc.json (old) { "rules": { "no-unused-vars": "error", "prefer-const": "warn" } }

// biome.json (new) { "linter": { "rules": { "correctness": { "noUnusedVariables": "error" }, "style": { "useConst": "warn" } } } }

4. Update Scripts

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

Git Hooks Integration

Using Husky + lint-staged

Install dependencies

npm install --save-dev husky lint-staged npx husky init

.husky/pre-commit :

#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

package.json :

{ "lint-staged": { "*.{js,ts,jsx,tsx,json}": [ "biome check --write --no-errors-on-unmatched" ] } }

Using Lefthook

lefthook.yml :

pre-commit: commands: lint: glob: "*.{js,ts,jsx,tsx,json}" run: biome check --write --no-errors-on-unmatched {staged_files}

Simple Git Hook (no dependencies)

.git/hooks/pre-commit :

#!/bin/bash

Get staged files

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '.(js|ts|jsx|tsx|json)$')

if [ -n "$STAGED_FILES" ]; then echo "Running Biome on staged files..." npx @biomejs/biome check --write --no-errors-on-unmatched $STAGED_FILES

Add formatted files back to staging

git add $STAGED_FILES fi

CI/CD Integration

GitHub Actions

name: Biome CI

on: push: branches: [main, develop] pull_request: branches: [main]

jobs: biome: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  - name: Install dependencies
    run: npm ci

  - name: Run Biome CI
    run: npx @biomejs/biome ci .

  - name: Check formatting
    run: npx @biomejs/biome format .

  - name: Lint
    run: npx @biomejs/biome lint .

GitLab CI

biome: image: node:20-alpine stage: test script: - npm ci - npx @biomejs/biome ci . cache: paths: - node_modules/ only: - merge_requests - main

CircleCI

version: 2.1

jobs: biome: docker: - image: cimg/node:20.11 steps: - checkout - restore_cache: keys: - deps-{{ checksum "package-lock.json" }} - run: npm ci - save_cache: paths: - node_modules key: deps-{{ checksum "package-lock.json" }} - run: npx @biomejs/biome ci .

workflows: test: jobs: - biome

Import Sorting

Biome includes built-in import sorting:

Organize imports

biome check --write --organize-imports-enabled=true .

Configuration:

{ "organizeImports": { "enabled": true } }

Example:

// Before import { useState } from 'react'; import axios from 'axios'; import { Button } from './components/Button'; import type { User } from './types'; import './styles.css';

// After (sorted) import type { User } from './types';

import axios from 'axios'; import { useState } from 'react';

import { Button } from './components/Button';

import './styles.css';

TypeScript Support

Biome has first-class TypeScript support:

{ "linter": { "rules": { "suspicious": { "noExplicitAny": "warn", "noUnsafeDeclarationMerging": "error" }, "correctness": { "noUnusedVariables": "error" }, "style": { "useImportType": "error", "useExportType": "error" } } } }

Type-aware linting:

// Biome detects unused variables const unused = 123; // ❌ Error

// Enforces type imports import { User } from './types'; // ❌ Error import type { User } from './types'; // ✅ Correct

// Detects unsafe type assertions const num = "123" as any as number; // ⚠️ Warning

Monorepo Support

Biome works great in monorepos:

Project Structure

my-monorepo/ ├── biome.json (root config) ├── packages/ │ ├── web/ │ │ └── biome.json (extends root) │ ├── api/ │ │ └── biome.json │ └── shared/ │ └── biome.json

Root Configuration

{ "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "extends": [], "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 }, "linter": { "enabled": true, "rules": { "recommended": true } } }

Package Override

{ "extends": ["../../biome.json"], "formatter": { "lineWidth": 100 }, "linter": { "rules": { "style": { "noNonNullAssertion": "off" } } } }

Monorepo Scripts

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

Performance Benefits

Speed Comparison

Tool Time (10,000 files)

ESLint + Prettier ~60s

Biome ~0.6s

100x faster on average workloads.

Caching

Biome includes intelligent caching:

First run (no cache)

biome check . # 1.2s

Second run (with cache)

biome check . # 0.1s

Clear cache

rm -rf node_modules/.cache/biome

Parallel Processing

Biome uses all CPU cores by default:

Limit CPU cores

biome check --max-diagnostics=50 .

Verbose output

biome check --verbose .

Common Patterns

React Projects

{ "linter": { "rules": { "a11y": { "recommended": true, "useButtonType": "error", "useKeyWithClickEvents": "error" }, "correctness": { "useExhaustiveDependencies": "warn", "useHookAtTopLevel": "error" }, "suspicious": { "noArrayIndexKey": "error" } } }, "javascript": { "formatter": { "jsxQuoteStyle": "double" } } }

Next.js Projects

{ "files": { "ignore": [".next", "out", "node_modules"] }, "overrides": [ { "include": ["app//*.tsx", "pages//*.tsx"], "linter": { "rules": { "a11y": { "recommended": true } } } } ] }

Node.js Backend

{ "linter": { "rules": { "security": { "recommended": true, "noGlobalEval": "error" }, "correctness": { "noUnusedVariables": "error" } } }, "javascript": { "formatter": { "semicolons": "always" } } }

Best Practices

• Use biome check instead of separate format/lint commands

• Enable --write flag for automatic fixes

• Configure VS Code for format-on-save

• Add git hooks to enforce quality before commits

• Use CI mode (biome ci ) in continuous integration

• Start with recommended rules then customize

• Leverage import sorting to organize imports automatically

• Use overrides for different file types or directories

• Enable VCS integration to respect .gitignore

• Keep configuration minimal - Biome has smart defaults

Troubleshooting

Biome Not Formatting

Check if formatter is enabled

biome rage

Verify file is not ignored

biome check --verbose src/file.ts

Check VS Code extension logs

View → Output → Biome

Conflicts with Prettier

Disable Prettier in VS Code settings

"[javascript]": { "editor.defaultFormatter": "biomejs.biome" }

Remove Prettier dependencies

npm uninstall prettier

Performance Issues

Check cache location

biome rage

Clear cache

rm -rf node_modules/.cache/biome

Reduce max diagnostics

biome check --max-diagnostics=20 .

Rule Configuration Not Working

// Ensure correct category { "linter": { "rules": { "correctness": { // Category name matters "noUnusedVariables": "error" } } } }

Local Biome Configs (Your Repos)

Patterns from active projects:

• ai-code-review/biome.json : files.includes targets src/**/*.ts and excludes tests, lineWidth: 100 , single quotes, semicolons always, and noExplicitAny: warn .

• itinerizer-ts/biome.json : files.ignore includes node_modules , dist , .claude , and data directories; organizeImports.enabled = true .

• matsuoka-com and diogenes use similar formatting defaults (2-space indent, lineWidth 100).

Common scripts:

{ "lint": "biome check src/ --diagnostic-level=error", "lint:fix": "biome check src/ --write", "format": "biome format src/ --write" }

Resources

• Official Docs: https://biomejs.dev

• VS Code Extension: https://marketplace.visualstudio.com/items?itemName=biomejs.biome

• GitHub: https://github.com/biomejs/biome

• Rules Reference: https://biomejs.dev/linter/rules/

• Migration Guide: https://biomejs.dev/guides/migrate-eslint-prettier/

Summary

• Biome is a fast all-in-one linter and formatter

• 100x faster than ESLint + Prettier

• Zero config by default with smart defaults

• Built in Rust for maximum performance

• TypeScript-first with excellent type support

• Import sorting included out of the box

• VS Code integration with official extension

• Perfect for modern web projects, monorepos, CI/CD

• Easy migration from ESLint and Prettier