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:

bash

npm install --save-dev @biomejs/biome

Quick Start

1. Initialize Biome

bash

# 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

json

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

3. Basic Configuration

json

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

bash

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

bash

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

bash

# 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

json

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

json

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

json

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

Override Configuration for Specific Files

json

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

VS Code Integration

1. Install Biome Extension

bash

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

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

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

json

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

bash

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

bash

# Migrate from Prettier config
biome migrate prettier --write

# Migrate from ESLint config
biome migrate eslint --write

3. Manual Migration

Prettier → Biome Formatter:

json

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

json

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

json

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

Git Hooks Integration

Using Husky + lint-staged

bash

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

.husky/pre-commit:

bash

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

npx lint-staged

package.json:

json

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

Using Lefthook

lefthook.yml:

yaml

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:

bash

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

yaml

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

yaml

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

CircleCI

yaml

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:

bash

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

Configuration:

json

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

Example:

typescript

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

json

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

Type-aware linting:

typescript

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

code

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

Root Configuration

json

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

json

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

Monorepo Scripts

json

{
  "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:

bash

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

bash

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

# Verbose output
biome check --verbose .

Common Patterns

React Projects

json

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

Next.js Projects

json

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

Node.js Backend

json

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

bash

# 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

bash

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

# Remove Prettier dependencies
npm uninstall prettier

Performance Issues

bash

# 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

json

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

json

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

Biome - Fast All-in-One Toolchain

Overview

Quick Start

1. Initialize Biome

2. Package.json Scripts

3. Basic Configuration

Core Commands

Check Command (Recommended)

Format Command

Lint Command

Configuration Deep Dive

Formatter Configuration

Linter Configuration

File Ignore Patterns

Override Configuration for Specific Files

VS Code Integration

1. Install Biome Extension

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

3. Workspace Settings

Migration from ESLint and Prettier

1. Remove Old Tools

2. Migrate Configuration

3. Manual Migration

4. Update Scripts

Git Hooks Integration

Using Husky + lint-staged

Using Lefthook

Simple Git Hook (no dependencies)

CI/CD Integration

GitHub Actions

GitLab CI

CircleCI

Import Sorting

TypeScript Support

Monorepo Support

Project Structure

Root Configuration

Package Override

Monorepo Scripts

Performance Benefits

Speed Comparison

Caching

Parallel Processing

Common Patterns

React Projects

Next.js Projects

Node.js Backend

Best Practices

Troubleshooting

Biome Not Formatting

Conflicts with Prettier

Performance Issues

Rule Configuration Not Working

Local Biome Configs (Your Repos)

Resources

Summary

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