Back to Details

biome

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Biome

Biome

Overview

概述

Biome is a fast Rust-based toolchain that combines formatting, linting, and import organization. 25x faster than Prettier, 15x faster than ESLint. Replaces ESLint + Prettier with single tool.
Key features (v2.0):
  • 97% Prettier compatibility, 340+ lint rules
  • Type-aware linting without TypeScript compiler
  • Supports: JS, TS, JSX, TSX, JSON, CSS, GraphQL
  • Framework domains: react, next, solid, test
Biome是一款基于Rust开发的快速工具链，整合了代码格式化、代码检查和导入组织功能。速度是Prettier的25倍，ESLint的15倍，可单工具替代ESLint + Prettier。
v2.0核心特性:
  • 97%兼容Prettier，拥有340+条检查规则
  • 无需TypeScript编译器即可实现类型感知的代码检查
  • 支持：JS、TS、JSX、TSX、JSON、CSS、GraphQL
  • 框架领域：react、next、solid、test

When to Use This Skill

何时使用该工具

  • Setting up linting/formatting for new project
  • Migrating from ESLint + Prettier
  • Configuring pre-commit hooks
  • Setting up CI code quality checks
  • Configuring monorepo linting
  • 为新项目配置代码检查/格式化
  • 从ESLint + Prettier迁移
  • 配置提交前钩子（pre-commit hooks）
  • 配置CI代码质量检查
  • 配置monorepo代码检查

Instructions

使用指南

1. Installation

1. 安装

bash
undefined
bash
undefined

npm/pnpm/yarn

npm/pnpm/yarn

npm install --save-dev --save-exact @biomejs/biome npx @biomejs/biome init
npm install --save-dev --save-exact @biomejs/biome npx @biomejs/biome init

Bun

Bun

bun add -D -E @biomejs/biome bunx @biomejs/biome init
undefined
bun add -D -E @biomejs/biome bunx @biomejs/biome init
undefined

2. Configuration (biome.json)

2. 配置（biome.json）

Recommended for React/TypeScript:
json
{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "domains": {
        "react": "recommended"
      },
      "correctness": {
        "noUnusedVariables": "error"
      },
      "nursery": {
        "noFloatingPromises": "error"
      }
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always"
    }
  },
  "organizeImports": {
    "enabled": true
  },
  "files": {
    "ignore": ["node_modules", "dist", "build", ".next", "coverage"]
  },
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  }
}
React/TypeScript推荐配置:
json
{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "domains": {
        "react": "recommended"
      },
      "correctness": {
        "noUnusedVariables": "error"
      },
      "nursery": {
        "noFloatingPromises": "error"
      }
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always"
    }
  },
  "organizeImports": {
    "enabled": true
  },
  "files": {
    "ignore": ["node_modules", "dist", "build", ".next", "coverage"]
  },
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  }
}

3. Package.json Scripts

3. Package.json脚本配置

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

4. Commands

4. 常用命令

bash
undefined
bash
undefined

Check all (lint + format + imports) - recommended

全量检查（代码检查+格式化+导入组织）—— 推荐使用

npx @biomejs/biome check --write
npx @biomejs/biome check --write

CI mode (fails on issues, no auto-fix)

CI模式（发现问题即失败，不自动修复）

npx @biomejs/biome ci
npx @biomejs/biome ci

Format only

仅格式化代码

npx @biomejs/biome format --write .
npx @biomejs/biome format --write .

Lint only

仅执行代码检查

npx @biomejs/biome lint --write .
undefined
npx @biomejs/biome lint --write .
undefined

Migration from ESLint/Prettier

从ESLint/Prettier迁移

bash
undefined
bash
undefined

Auto-migrate configs

自动迁移配置

npx @biomejs/biome migrate eslint --write npx @biomejs/biome migrate prettier --write

**Manual steps:**
1. Run migration commands
2. Review generated `biome.json`
3. Delete: `.eslintrc.*`, `.prettierrc.*`, `.eslintignore`, `.prettierignore`
4. Remove ESLint/Prettier from `package.json`
5. Update pre-commit hooks and CI
npx @biomejs/biome migrate eslint --write npx @biomejs/biome migrate prettier --write

**手动步骤:**
1. 执行上述迁移命令
2. 检查生成的`biome.json`配置
3. 删除：`.eslintrc.*`, `.prettierrc.*`, `.eslintignore`, `.prettierignore`
4. 从`package.json`中移除ESLint/Prettier依赖
5. 更新提交前钩子和CI配置

Biome v2 Features

Biome v2新特性

Domains

框架领域配置

Enable framework-specific rules automatically:
json
{
  "linter": {
    "rules": {
      "domains": {
        "react": "recommended",
        "next": "recommended",
        "test": "all"
      }
    }
  }
}
Biome auto-detects from 
package.json
dependencies.
自动启用框架专属规则：
json
{
  "linter": {
    "rules": {
      "domains": {
        "react": "recommended",
        "next": "recommended",
        "test": "all"
      }
    }
  }
}
Biome会自动从
package.json
的依赖中检测框架。

Type Inference (Biotype)

类型推断（Biotype）

Type-aware linting without TypeScript compiler (~85% coverage):
json
{
  "linter": {
    "rules": {
      "nursery": {
        "noFloatingPromises": "error"
      }
    }
  }
}
无需TypeScript编译器即可实现类型感知的代码检查（约85%覆盖率）：
json
{
  "linter": {
    "rules": {
      "nursery": {
        "noFloatingPromises": "error"
      }
    }
  }
}

Multi-file Analysis

多文件分析

json
{
  "linter": {
    "rules": {
      "nursery": {
        "noImportCycles": "error",
        "noPrivateImports": "error"
      }
    }
  }
}
json
{
  "linter": {
    "rules": {
      "nursery": {
        "noImportCycles": "error",
        "noPrivateImports": "error"
      }
    }
  }
}

Suppressions

规则忽略

typescript
// Single line
// biome-ignore lint/suspicious/noExplicitAny: legacy code
const data: any = fetchData();

// Entire file
// biome-ignore-all lint/suspicious/noExplicitAny

// Range
// biome-ignore-start lint/style/noVar
var legacy = "code";
// biome-ignore-end
typescript
// 单行忽略
// biome-ignore lint/suspicious/noExplicitAny: legacy code
const data: any = fetchData();

// 整个文件忽略
// biome-ignore-all lint/suspicious/noExplicitAny

// 范围忽略
// biome-ignore-start lint/style/noVar
var legacy = "code";
// biome-ignore-end

Monorepo Setup

Monorepo配置

Root config:
json
{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "formatter": { "indentStyle": "space", "indentWidth": 2 },
  "linter": { "rules": { "recommended": true } }
}
Package config (
packages/web/biome.json
):
json
{
  "root": false,
  "extends": "//",
  "linter": {
    "rules": {
      "domains": { "react": "recommended" }
    }
  }
}
根目录配置:
json
{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "formatter": { "indentStyle": "space", "indentWidth": 2 },
  "linter": { "rules": { "recommended": true } }
}
子包配置（
packages/web/biome.json
）:
json
{
  "root": false,
  "extends": "//",
  "linter": {
    "rules": {
      "domains": { "react": "recommended" }
    }
  }
}

Pre-commit Hooks

提交前钩子配置

Lefthook (Recommended)

Lefthook（推荐）

bash
npm install -D lefthook
npx lefthook install
lefthook.yml:
yaml
pre-commit:
  commands:
    biome:
      run: npx @biomejs/biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
      stage_fixed: true
bash
npm install -D lefthook
npx lefthook install
lefthook.yml:
yaml
pre-commit:
  commands:
    biome:
      run: npx @biomejs/biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
      stage_fixed: true

Husky + lint-staged

Husky + lint-staged

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

VS Code Integration

VS Code集成

Install: Biome VS Code Extension
.vscode/settings.json:
json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "biome.enabled": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "source.fixAll.biome": "explicit"
  }
}
安装：Biome VS Code扩展
.vscode/settings.json:
json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "biome.enabled": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "source.fixAll.biome": "explicit"
  }
}

CI (GitHub Actions)

CI配置（GitHub Actions）

yaml
name: Code Quality
on: [push, pull_request]

jobs:
  biome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: biomejs/setup-biome@v2
      - run: biome ci --changed
yaml
name: Code Quality
on: [push, pull_request]

jobs:
  biome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: biomejs/setup-biome@v2
      - run: biome ci --changed

Quick Reference

快速参考

TaskCommand
Check all + fix
biome check --write .
CI mode
biome ci .
Lint only
biome lint .
Format only
biome format --write .
Migrate ESLint
biome migrate eslint --write
Migrate Prettier
biome migrate prettier --write
任务命令
全量检查并修复
biome check --write .
CI模式
biome ci .
仅代码检查
biome lint .
仅代码格式化
biome format --write .
从ESLint迁移
biome migrate eslint --write
从Prettier迁移
biome migrate prettier --write

Guidelines

最佳实践

Do

推荐做法

  • Use 
    biome check --write
    as primary command (lint + format + imports)
  • Commit 
    biome.json
    to repo
  • Use 
    --changed
    in CI for speed
  • Enable relevant domains (react, next, test)
  • Use 
    --no-errors-on-unmatched
    in hooks
  • 使用
    biome check --write
    作为核心命令（整合代码检查+格式化+导入组织）
  • 将
    biome.json
    提交到代码仓库
  • 在CI中使用
    --changed
    参数提升速度
  • 启用对应框架领域的规则（react、next、test）
  • 在钩子中使用
    --no-errors-on-unmatched
    参数

Don't

不推荐做法

  • Mix Biome with ESLint/Prettier in same project
  • Forget to remove old linter configs after migration
  • Skip 
    --write
    flag when you want auto-fix
  • Ignore 
    nursery
    rules - they have useful type-aware checks
  • 在同一项目中同时使用Biome与ESLint/Prettier
  • 迁移后忘记删除旧的代码检查工具配置
  • 需要自动修复时省略
    --write
    参数
  • 忽略
    nursery
    规则——它们包含实用的类型感知检查

Limitations

局限性与解决方案

LimitationWorkaround
JSON-only configUse 
extends
for shared configs
Vue/Svelte/AstroPartial support (improving)
YAML/MarkdownNot supported
Some ESLint pluginsCheck rule compatibility
局限性解决方案
仅支持JSON格式配置使用
extends
参数共享配置
Vue/Svelte/Astro支持有限支持正在持续优化
不支持YAML/Markdown暂无解决方案
部分ESLint插件不兼容提前检查规则兼容性