ultracite

Ultracite

零配置的 JS/TS 项目代码检查与格式化。支持三种代码检查后端：Biome（推荐）、ESLint + Prettier + Stylelint 以及 Oxlint + Oxfmt。

检测 Ultracite

检查 package.json 的 dependencies 或 devDependencies 中是否包含 ultracite。通过查找以下文件（从当前目录向上搜索）来检测当前使用的代码检查工具：

biome.json / biome.jsonc → Biome
eslint.config.*（.mjs、.js、.cjs、.ts、.mts、.cts）→ ESLint（配合 Prettier 进行格式化）
oxlint.config.ts → Oxlint（配合 oxfmt.config.ts 进行格式化）

CLI 命令

# 检查问题（只读）
bunx ultracite check

# 自动修复问题
bunx ultracite fix

# 诊断设置问题
bunx ultracite doctor

# 在新项目中初始化
bunx ultracite init

根据包管理器将 bunx 替换为 npx、pnpx 或 yarn dlx。

check 和 fix 可以接受可选的文件路径：bunx ultracite check src/index.ts。未知选项会透传给底层代码检查工具（例如 bunx ultracite check --max-warnings 0）。

初始化

bunx ultracite init 运行交互式设置。对于非交互式（CI）使用，请传递标志：

bunx ultracite init \
  --pm bun \
  --linter biome \
  --editors universal \
  --agents claude copilot \
  --frameworks react next \
  --integrations husky lint-staged \
  --quiet

标志：

--pm — npm | yarn | pnpm | bun
--linter — biome（推荐）| eslint | oxlint
--editors — universal（为每个基于 VS Code 的编辑器写入 .vscode/settings.json）| vscode | cursor | windsurf | codebuddy | antigravity | bob | kiro | trae | void | zed
--agents — universal（写入 AGENTS.md）| claude | codex | copilot | cline | amp | gemini | cursor-cli + 另外 34 个（共支持 41 个代理）
--frameworks — react | next | solid | vue | svelte | qwik | remix | tanstack | angular | astro | nestjs | jest | vitest
--integrations — husky | lefthook | lint-staged | pre-commit
--hooks — 启用自动修复钩子：claude | copilot | cursor | windsurf | codebuddy
--type-aware — 启用类型感知代码检查（Biome：扩展 type-aware 预设；Oxlint：安装 oxlint-tsgolint）
--install-skill — 设置后安装可复用的 Ultracite 技能
--skip-install — 跳过依赖安装
--quiet — 抑制提示（当 CI=true 时自动检测）

初始化会创建扩展 Ultracite 预设的配置：

// biome.jsonc
{ "extends": ["ultracite/biome/core", "ultracite/biome/react"] }

// eslint.config.mjs — 扁平配置数组，展开合并
import core from "ultracite/eslint/core";
import react from "ultracite/eslint/react";
export default [...core, ...react];

// oxlint.config.ts — 导入传递给 extends
import { defineConfig } from "oxlint";
import core from "ultracite/oxlint/core";
export default defineConfig({
  extends: [core],
  ignorePatterns: core.ignorePatterns,
});

每个代码检查工具可用的预设（ultracite/<linter>/<preset>）：core、react、next、solid、vue、svelte、qwik、remix、tanstack、angular、astro、nestjs、jest、vitest。Biome 还有 type-aware；Oxlint 还有 github 和 sonarjs（通过 oxlint 的 JS 插件支持运行 ESLint 插件，初始化时默认包含）。

代码规范

在使用了 Ultracite 的项目中编写代码时，请遵循以下规范。完整规则参考请参见 references/code-standards.md。

关键规则一览：

格式化由项目配置的代码检查工具/格式化工具处理。请尊重仓库现有的格式化设置，而不是强制使用固定的行宽、引号样式或尾逗号策略。

类型安全： 当显式类型能提高清晰度时使用。优先使用 unknown 而非 any。对不可变值使用 as const，依赖类型收窄而非粗暴断言。

现代 JavaScript/TypeScript： 优先使用 const、解构、可选链、空值合并、模板字面量、for...of 和简洁箭头函数。

异步与正确性： 在异步函数中始终 await promise。优先使用 async/await 而非 promise 链。从生产代码中移除 console.log、debugger 和 alert。

React 与可访问性： 使用函数组件，保持钩子在顶层并具有正确的依赖，避免嵌套组件定义，使用语义化 HTML 并配备正确的标签、标题、替代文本和键盘操作支持。

组织、安全、性能与测试： 保持函数专注，优先使用提前返回，避免 dangerouslySetInnerHTML 和 eval()，优先使用具体导入和顶层正则表达式，保持测试中不含 .only 和 .skip。

故障排除

运行 bunx ultracite doctor 进行诊断。它会检查：

代码检查工具和格式化工具的安装（Biome；或 ESLint + Prettier + Stylelint；或 Oxlint + oxfmt）
配置有效性（是否正确扩展了 Ultracite 预设）
package.json 依赖中是否包含 Ultracite
冲突工具（遗留的 .eslintrc.* 文件；未使用 ESLint 后端时的 .prettierrc.*/prettier.config.* 文件）

常见修复：