linter-formatter-init

Linter Formatter Init

使用 Biome 2.3+（默认）、Vitest 和 Bun 为 JavaScript/TypeScript 项目设置代码检查、格式化和测试。

重要提示：始终使用 Biome 2.3+（最新版本），切勿使用更早的版本。

约定

输入：

• 目标代码库，以及选定的格式化工具、测试和钩子选项

输出：

• 配置好的代码质量工具和变更摘要

创建/修改：

• 仅创建或修改设置中选定的配置、脚本和依赖项

外部副作用：

• 安装软件包和获准的本地验证

所需确认：

• 覆盖现有配置或安装明确请求的设置之外的工具之前
• 加载该技能不会授予额外权限。现有的明确批准仅适用于相同目标和操作；请保留仅报告限制。

委托给：

• 无

用途

此技能可自动设置：

• Biome，用于代码检查和格式化（默认且推荐）
• Vitest，用于测试和覆盖率（使用 --vitest 标志）
• ESLint + Prettier（旧方案，使用 --eslint 标志）
• Husky + lint-staged，用于提交前钩子
• VS Code/Cursor 设置，用于保存时自动格式化
• 用于手动执行代码检查、格式化和测试的 bun 脚本

适用场景

• 启动新的 JS/TS 项目
• 为尚未配置工具的现有项目添加代码检查
• 在团队中统一代码质量标准
• 设置提交前钩子以保障代码质量

快速开始

# Default setup (Biome) - RECOMMENDED
python3 scripts/setup.py --root /path/to/project

# Add Vitest testing with 80% coverage threshold
python3 scripts/setup.py --root /path/to/project --vitest --coverage 80

# Use ESLint + Prettier instead (legacy)
python3 scripts/setup.py --root /path/to/project --eslint --typescript

有关 --no-hooks、--monorepo 以及所有标志组合，请参阅 references/full-guide.md（§ 快速开始 — 完整命令变体）。

安装内容

依赖项

Biome 2.3+（默认）： @biomejs/biome@latest（始终为最新版本，最低要求为 2.3+）

Vitest（使用 --vitest 时）： vitest、@vitest/coverage-v8

ESLint + Prettier（旧方案，使用 --eslint 时）： eslint、prettier、eslint-config-prettier、eslint-plugin-prettier；如果使用 --typescript，还会安装 @typescript-eslint/parser 和 @typescript-eslint/eslint-plugin

提交前钩子： husky、lint-staged

配置文件（Biome - 默认）

project/
├── biome.json              # Biome config (lint + format)
├── .vscode/settings.json   # Auto-format on save
├── .husky/pre-commit       # Pre-commit hook
└── package.json            # Updated with scripts + lint-staged

ESLint + Prettier（旧方案）会生成等效的 .eslintrc.json / .prettierrc 结构，详见 references/full-guide.md（§ 配置文件（ESLint + Prettier - 旧方案））。

添加的 Bun 脚本

Biome 会添加 lint、lint:fix、format、format:check、check、check:fix。Vitest 会添加 test、test:watch、test:coverage、test:ui。ESLint + Prettier（旧方案）会添加 lint、lint:fix、format、format:check。确切的脚本命令请参阅 references/full-guide.md（§ 添加的 Bun 脚本）。

Biome 配置（默认）

Biome 是一款快速的一体化代码检查和格式化工具。默认配置会启用推荐的代码检查规则、2 个空格缩进/100 个字符的格式、单引号和 organizeImports。完整的 biome.json 请参阅 references/full-guide.md（§ Biome 配置（默认））。

设置完成后，可自定义 biome.json，调整代码检查规则、格式偏好和文件忽略模式。

Vitest 配置（使用 --vitest 时）

--vitest 标志会创建 vitest.config.ts（node/jsdom 环境、v8 覆盖率、默认阈值为 80%）和用于全局测试设置的 src/test/setup.ts。这两个文件的完整内容请参阅 references/full-guide.md（§ Vitest 配置（使用 --vitest 时））。

使用 --coverage 90 自定义覆盖率阈值。

提交前钩子

启用时（默认），lint-staged 会在每次提交时运行：

Biome： *.{js,jsx,ts,tsx,json,css} → bunx biome check --write

ESLint + Prettier（旧方案）： *.{js,jsx,ts,tsx} → eslint --fix、prettier --write；*.{json,md,yml,yaml} → prettier --write

这样可确保所有提交的代码都通过代码检查并完成格式化，且不会将有问题的代码引入代码库。

VS Code / Cursor 集成

该技能会创建 .vscode/settings.json，启用保存时自动格式化，并将 Biome（默认）或 Prettier/ESLint（旧方案）设为默认格式化工具。两种完整配置请参阅 references/full-guide.md（§ VS Code / Cursor 设置）。

为什么选择 Biome，而不是 ESLint + Prettier？

• 更快：使用 Rust 编写，速度比 ESLint + Prettier 快 10–100 倍
• 更简单：一个工具取代两个工具，只需一个配置文件
• 无冲突：无需使用 eslint-config-prettier 或类似的变通方案
• 默认配置更好：开箱即用的合理规则

支持 Monorepo

在根目录运行 python3 scripts/setup.py --root /path/to/monorepo --monorepo。这会添加适用于所有包的根级配置。

故障排除

Pre-commit 钩子未运行

bunx husky
chmod +x .husky/pre-commit

Biome 保存时未格式化

1. 在 VS Code/Cursor 中安装 Biome 扩展
2. 将 Biome 设为默认格式化程序
3. 在设置中启用“保存时格式化”

ESLint + Prettier 保存时未格式化

1. 在 VS Code/Cursor 中安装 Prettier 扩展
2. 将 Prettier 设为默认格式化程序
3. 在设置中启用“保存时格式化”

特定框架的配置（仅限 ESLint 模式）

使用 --eslint 时，该技能会检测常见框架并调整配置：

• Next.js：向 ESLint 添加 next/core-web-vitals
• React：添加 eslint-plugin-react 和 eslint-plugin-react-hooks
• NestJS：添加适用于装饰器和 DI 模式的规则

手动设置（替代方案）

如果更倾向于手动设置，而非运行脚本：

# Biome
bun add -D @biomejs/biome husky lint-staged
bunx biome init && bunx husky

请参阅 references/full-guide.md（§ 手动设置（替代设置脚本）），了解 ESLint + Prettier 的手动配置步骤，然后从 assets/configs/ 复制配置。