Biome

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:

bashCopy code
npm install --save-dev @biomejs/biome

Quick Start

1. Initialize Biome

bashCopy code
# 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

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

3. Basic Configuration

jsonCopy code
{
  "$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:

bashCopy code
# 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:

bashCopy code
# 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:

bashCopy code
# 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

jsonCopy code
{
  "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

jsonCopy code
{
  "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

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

Override Configuration for Specific Files

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

VS Code Integration

1. Install Biome Extension

bashCopy code
# Install from VS Code marketplace
code --install-extension biomejs.biome

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

jsonCopy code
{
  "[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

jsonCopy code
{
  "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

bashCopy code
# 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:

bashCopy code
# Migrate from Prettier config
biome migrate prettier --write

# Migrate from ESLint config
biome migrate eslint --write

3. Manual Migration

Prettier → Biome Formatter:

jsonCopy code
// .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:

jsonCopy code
// .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

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

Git Hooks Integration

Using Husky + lint-staged

bashCopy code
# Install dependencies
npm install --save-dev husky lint-staged
npx husky init

.husky/pre-commit:

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

npx lint-staged

package.json:

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

Using Lefthook

lefthook.yml:

yamlCopy code
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:

bashCopy code
#!/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

yamlCopy code
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

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

CircleCI

yamlCopy code
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:

bashCopy code
# Organize imports
biome check --write --organize-imports-enabled=true .

Configuration:

jsonCopy code
{
  "organizeImports": {
    "enabled": true
  }
}

Example:

typescriptCopy code
// 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:

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

Type-aware linting:

typescriptCopy code
// 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

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

Root Configuration

jsonCopy code
{
  "$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

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

Monorepo Scripts

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

Performance Benefits

Speed Comparison

100x faster on average workloads.

Caching

Biome includes intelligent caching:

bashCopy code
# 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:

bashCopy code
# Limit CPU cores
biome check --max-diagnostics=50 .

# Verbose output
biome check --verbose .

Common Patterns

React Projects

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

Next.js Projects

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

Node.js Backend

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

Best Practices

1. Use biome check instead of separate format/lint commands
2. Enable --write flag for automatic fixes
3. Configure VS Code for format-on-save
4. Add git hooks to enforce quality before commits
5. Use CI mode (biome ci) in continuous integration
6. Start with recommended rules then customize
7. Leverage import sorting to organize imports automatically
8. Use overrides for different file types or directories
9. Enable VCS integration to respect .gitignore
10. Keep configuration minimal - Biome has smart defaults

Troubleshooting

Biome Not Formatting

bashCopy code
# 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

bashCopy code
# Disable Prettier in VS Code settings
"[javascript]": {
  "editor.defaultFormatter": "biomejs.biome"
}

# Remove Prettier dependencies
npm uninstall prettier

Performance Issues

bashCopy code
# 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

jsonCopy code
// 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:

jsonCopy code
{
  "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