biome

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Biome - Professional TypeScript/JavaScript Tooling

Biome - 专业TypeScript/JavaScript工具链

Biome is a fast, modern toolchain for JavaScript, TypeScript, JSX, JSON, CSS, GraphQL, and HTML. It provides formatting, linting, and code analysis with a single tool and zero configuration required.

Biome是一款面向JavaScript、TypeScript、JSX、JSON、CSS、GraphQL和HTML的快速现代化工具链。它通过单一工具提供格式化、代码检查和代码分析功能，且无需任何配置即可使用。

When to Use This Skill

何时使用该技能

Use this skill when:

Setting up Biome in a new or existing project
Configuring biome.json for specific requirements
Migrating from ESLint and/or Prettier to Biome
Implementing linter rules or formatter options
Integrating Biome with editors (VS Code, Zed, IntelliJ)
Setting up CI/CD pipelines with Biome
Configuring monorepos or large projects
Debugging Biome configuration or performance issues
Understanding specific lint rules or code actions
Upgrading from Biome v1 to v2

在以下场景中使用该技能：

在新项目或现有项目中搭建Biome环境
根据特定需求配置biome.json
从ESLint和/或Prettier迁移至Biome
配置检查器规则或格式化选项
将Biome与编辑器（VS Code、Zed、IntelliJ）集成
搭建基于Biome的CI/CD流水线
配置单仓库（monorepo）或大型项目
调试Biome配置或性能问题
了解特定检查规则或代码操作
从Biome v1升级至v2

Quick Start

快速开始

Installation

安装

bash

undefined

bash

undefined

npm

npm i -D -E @biomejs/biome

pnpm

pnpm add -D -E @biomejs/biome

yarn

yarn add -D -E @biomejs/biome

undefined

yarn add -D -E @biomejs/biome

undefined

Initialize Configuration

初始化配置

bash

npx @biomejs/biome init

This creates a

biome.json

with recommended defaults.

bash

npx @biomejs/biome init

该命令会生成一个包含推荐默认配置的

biome.json

文件。

Basic Commands

基础命令

bash

undefined

bash

undefined

Format and lint

格式化并检查代码

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

Format only

仅格式化代码

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

Lint only

仅检查代码

npx @biomejs/biome lint ./src

CI mode (no writes, exit on errors)

CI模式（不写入文件，遇错误即退出）

npx @biomejs/biome ci ./src

undefined

npx @biomejs/biome ci ./src

undefined

Core Workflows

核心工作流

1. Project Setup

1. 项目搭建

For new projects:

Install Biome as dev dependency
Run
```
npx @biomejs/biome init
```
Configure
```
biome.json
```
for project needs
Add scripts to package.json
Set up editor integration
Configure CI/CD

See references/docs/guides/getting-started.md for details.

针对新项目：

将Biome安装为开发依赖
运行
```
npx @biomejs/biome init
```
根据项目需求配置
```
biome.json
```
在package.json中添加脚本
搭建编辑器集成环境
配置CI/CD

详情请参考references/docs/guides/getting-started.md。

2. Configuration

2. 配置

Biome configuration lives in

biome.json

biome.jsonc

. Key sections:

```
$schema
```
- JSON schema for IDE autocomplete
```
files
```
- File inclusion/exclusion patterns
```
formatter
```
- Formatting options (indentation, line width, etc.)
```
linter
```
- Linting rules and their configuration
```
javascript
```
,
```
json
```
,
```
css
```
- Language-specific options
```
overrides
```
- Per-file or per-directory overrides

For complete configuration reference, see references/docs/reference/configuration.md.

Biome的配置存储在

biome.json

或

biome.jsonc

中。核心配置项：

```
$schema
```
- 用于IDE自动补全的JSON Schema
```
files
```
- 文件包含/排除规则
```
formatter
```
- 格式化选项（缩进方式、行宽等）
```
linter
```
- 检查器规则及其配置
```
javascript
```
,
```
json
```
,
```
css
```
- 特定语言的配置选项
```
overrides
```
- 针对文件或目录的覆盖配置

完整配置参考请见references/docs/reference/configuration.md。

3. Migration from ESLint/Prettier

3. 从ESLint/Prettier迁移

Biome can replace both ESLint and Prettier in most projects:

Audit existing ESLint/Prettier config
Map rules to Biome equivalents
Configure Biome to match existing style
Run side-by-side comparison
Remove ESLint/Prettier dependencies
Update scripts and CI/CD

See references/docs/guides/migrate-eslint-prettier.md for detailed migration guide.

Biome可在大多数项目中替代ESLint和Prettier：

审核现有ESLint/Prettier配置
将现有规则映射为Biome等效规则
配置Biome以匹配现有代码风格
运行双向对比验证
移除ESLint/Prettier依赖
更新脚本和CI/CD配置

详细迁移指南请参考references/docs/guides/migrate-eslint-prettier.md。

4. Monorepo/Large Projects

4. 单仓库/大型项目

For monorepos or projects with multiple packages:

Create root
```
biome.json
```
with shared config
Use
```
extends
```
in package-specific configs
Configure file patterns for each package
Set up workspace-aware linting
Optimize for performance

See references/docs/guides/big-projects.md for monorepo patterns.

针对单仓库或多包项目：

创建根目录
```
biome.json
```
作为共享配置
在包级配置中使用
```
extends
```
继承根配置
为每个包配置文件规则
搭建支持工作区的代码检查
优化性能

单仓库配置模式请参考references/docs/guides/big-projects.md。

5. Editor Integration

5. 编辑器集成

Biome has official extensions for:

VS Code - Full LSP support, format on save, quick fixes
Zed - Native integration, inline diagnostics
IntelliJ - Plugin available

Install the extension for your editor and configure workspace settings. See references/docs/guides/editors_first-party-extensions.md.

Biome拥有官方扩展支持以下编辑器：

VS Code - 完整LSP支持、保存时格式化、快速修复
Zed - 原生集成、内联诊断
IntelliJ - 提供插件支持

安装对应编辑器的扩展并配置工作区设置。详情请见references/docs/guides/editors_first-party-extensions.md。

Reference Documentation

参考文档

This skill includes complete Biome v2.x documentation:

该技能包含完整的Biome v2.x文档：

Essential References

核心参考

INDEX.md - Complete documentation index
CLI Reference - All commands and options (70 KB)
Configuration Reference - All config options (42 KB)
JavaScript Rules - Complete rule list (68 KB)

INDEX.md - 完整文档索引
CLI参考 - 所有命令及选项（70 KB）
配置参考 - 所有配置选项（42 KB）
JavaScript规则 - 完整规则列表（68 KB）

Documentation Categories

文档分类

Guides (11 files)

Getting started, configuration, migration, editor setup, monorepos

Formatter (3 files)

Formatting engine, Prettier differences, design philosophy

Linter (13 files)

Linting rules for JavaScript/TypeScript, CSS, JSON, GraphQL, HTML
Rule sources and framework-specific domains (React, Next.js, etc.)

Assist (9 files)

Code actions and refactoring capabilities for all languages

Reference (8 files)

CLI, configuration, diagnostics, environment variables, reporters, editor extensions

Recipes (4 files)

CI/CD integration, git hooks, Renovate setup, badges

Internals (7 files)

Architecture, philosophy, language support, versioning, changelogs

Use references/INDEX.md for quick navigation to specific topics.

指南（11份文件）

入门、配置、迁移、编辑器设置、单仓库

格式化工具（3份文件）

格式化引擎、与Prettier的差异、设计理念

检查器（13份文件）

JavaScript/TypeScript、CSS、JSON、GraphQL、HTML的检查规则
规则来源及框架专属规则（React、Next.js等）

辅助功能（9份文件）

全语言的代码操作和重构能力

参考手册（8份文件）

CLI、配置、诊断、环境变量、报告器、编辑器扩展

实践方案（4份文件）

CI/CD集成、Git钩子、Renovate配置、徽章

内部实现（7份文件）

架构、设计理念、语言支持、版本控制、更新日志

使用references/INDEX.md可快速导航至特定主题。

Common Patterns

常见配置模式

Typical biome.json

典型biome.json配置

json

{
  "$schema": "https://biomejs.dev/schemas/2.0.5/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false,
    "includes": ["src/**/*"]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  }
}

json

{
  "$schema": "https://biomejs.dev/schemas/2.0.5/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false,
    "includes": ["src/**/*"]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  }
}

Package.json Scripts

Package.json脚本配置

json

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

json

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

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions

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


See [references/docs/recipes/continuous-integration.md](references/docs/recipes/continuous-integration.md) for complete CI/CD examples.

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


完整CI/CD示例请参考[references/docs/recipes/continuous-integration.md](references/docs/recipes/continuous-integration.md)。

Updating Documentation

更新文档

To update this skill's documentation with the latest from biomejs.dev:

bash

python scripts/scrape_biome_docs.py --update-all --output references/docs

This scrapes all current documentation and updates the reference files.

如需从biomejs.dev获取最新文档更新本技能：

bash

python scripts/scrape_biome_docs.py --update-all --output references/docs

该脚本会抓取所有当前文档并更新参考文件。

Key Concepts

核心概念

Formatting Philosophy

格式化理念

Opinionated defaults with minimal configuration
Focuses on consistency over personal preference
Significantly faster than Prettier (10-20x)
Format-preserving when possible

自带约定式默认配置，需极少自定义
优先保障一致性而非个人偏好
速度显著快于Prettier（10-20倍）
尽可能保留原有格式

Linting Approach

检查器设计

Rules organized by category (correctness, performance, style, etc.)
Framework-aware domains (React, Next.js, etc.)
Recommended rules enabled by default
Fast incremental linting

规则按类别组织（正确性、性能、风格等）
支持框架专属规则（React、Next.js等）
默认启用推荐规则
快速增量检查

Tool Integration

工具集成

Single tool replaces ESLint + Prettier + more
Zero-config defaults work for most projects
Native TypeScript support, no type-checking required
Incremental adoption possible

单一工具替代ESLint + Prettier及更多工具
零配置默认值适用于大多数项目
原生TypeScript支持，无需类型检查
支持渐进式 adoption

Best Practices

最佳实践

Start with recommended rules - Enable
```
"recommended": true
```
then customize
Use VCS integration - Let Biome respect .gitignore
Pin Biome version - Use exact versions in package.json
Configure per-language - Override general settings for specific languages
Use overrides sparingly - Prefer consistent configuration across the project
Test before committing - Run
```
biome ci
```
in CI/CD
Enable editor integration - Format on save for best experience
Read diagnostics carefully - Biome provides detailed error explanations

从推荐规则开始 - 先启用
```
"recommended": true
```
再按需自定义
启用VCS集成 - 让Biome遵循.gitignore规则
固定Biome版本 - 在package.json中使用精确版本
按语言配置 - 针对特定语言覆盖全局设置
谨慎使用覆盖配置 - 优先保障项目配置一致性
提交前测试 - 在CI/CD中运行
```
biome ci
```
启用编辑器集成 - 开启保存时格式化以获得最佳体验
仔细阅读诊断信息 - Biome提供详细的错误说明

Troubleshooting

故障排查

Common issues and solutions:

Biome not finding files

Check
```
files.includes
```
in biome.json
Verify VCS integration settings
Review .gitignore patterns

Performance issues

See references/docs/guides/investigate-slowness.md
Check file inclusion patterns
Consider using
```
files.ignoreUnknown
```

Rule conflicts with existing code

Use suppressions for one-off cases
Configure rule severity (error/warn/off)
See references/docs/analyzer/suppressions.md

Migration issues

Compare Biome output with ESLint/Prettier
Use configuration overrides for edge cases
See migration guide for common patterns

For detailed troubleshooting, consult the relevant reference documentation.

常见问题及解决方案：

Biome无法找到文件

检查biome.json中的
```
files.includes
```
配置
验证VCS集成设置
查看.gitignore规则

性能问题

参考references/docs/guides/investigate-slowness.md
检查文件包含规则
考虑启用
```
files.ignoreUnknown
```

规则与现有代码冲突

对个别情况使用抑制规则
配置规则严重程度（错误/警告/关闭）
参考references/docs/analyzer/suppressions.md

迁移问题

对比Biome与ESLint/Prettier的输出
针对边缘情况使用覆盖配置
参考迁移指南中的常见模式

详细故障排查请查阅对应参考文档。

Resources

资源

scripts/

Contains the Biome documentation scraper for keeping this skill up to date:

```
scrape_biome_docs.py
```
- Scrapes and cleans Biome documentation from biomejs.dev

包含用于同步Biome最新文档的抓取脚本：

```
scrape_biome_docs.py
```
- 从biomejs.dev抓取并整理Biome文档

references/

Complete Biome v2.x documentation (56 files, 896 KB):

```
INDEX.md
```
- Navigation index for all documentation
```
docs/
```
- All scraped and cleaned documentation files organized by category

The documentation is comprehensive and production-ready, covering all aspects of Biome from installation to advanced usage patterns.

完整的Biome v2.x文档（56份文件，896 KB）：

```
INDEX.md
```
- 所有文档的导航索引
```
docs/
```
- 按类别组织的所有抓取并整理后的文档

该文档全面且可用于生产环境，涵盖了Biome从安装到高级使用模式的所有方面。