ultracite

Ultracite

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

检测 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.config.mts 或 .oxlintrc.json → Oxlint（使用 oxfmt.config.ts 或 oxfmt.config.mts 格式化；在非 ES 模块的包中，init 会写入 .mts 格式）

CLI 命令

# Check for issues (read-only)
bunx ultracite check

# Auto-fix issues
bunx ultracite fix

# Diagnose setup problems
bunx ultracite doctor

# Initialize in a new project
bunx ultracite init

根据包管理器，将 bunx 替换为 npx、pnpm exec 或 yarn，以便运行项目已安装的 Ultracite（pnpm dlx 和 yarn dlx 会改为下载最新版本，而 Yarn 1 不支持 dlx）。只有在尚未安装 Ultracite 的项目中运行 init 时，才需要使用 pnpm 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 \
  --yes

标志：

• --pm — npm | yarn | pnpm | bun | deno | nub | aube
• --linter — oxlint（推荐）| biome | eslint
• --editors — universal（为所有基于 VS Code 的编辑器写入 .vscode/settings.json）| vscode | cursor | devin | codebuddy | antigravity | bob | kiro | trae | void | zed
• --agents — 所有选项都会将规则写入 AGENTS.md。universal 只写入该文件；claude、gemini、aider 和 replit 还会添加相应 Agent 读取规则所需的导入、设置或副本；codex、copilot、cline、amp 和 cursor-cli 等 ID（支持 40 个 Agent）无需额外操作
• --frameworks — react | next | solid | vue | svelte | qwik | remix | tanstack | angular | astro | nestjs | jest | vitest | cypress | storybook | playwright | react-native | drizzle
• --integrations — husky | lefthook | lint-staged | pre-commit
• --hooks — 启用自动修复钩子：claude | codex | copilot | cursor | devin | codebuddy | deepagents | grok
• --js-plugins — 选择启用 Oxlint JS 插件：@shadcn/lint | anti-slop | eslint-plugin-github | eslint-plugin-jsdoc | eslint-plugin-sonarjs | eslint-plugin-tsdoc | oxlint-plugin-react-doctor
• --type-aware — 启用类型感知 lint（ESLint 和 Biome：扩展其 type-aware 预设；Oxlint：安装 oxlint-tsgolint 并设置 typeAware），并在 tsconfig 文件中启用 strictNullChecks
• --install-skill — 设置完成后安装可复用的 Ultracite 技能
• --skip-install — 跳过依赖项安装
• --yes、-y — 不提示并采用默认值（当 CI=true 或没有终端时自动启用）；未提供 --linter 时，默认使用 oxlint
• --quiet — 仅打印警告和错误

Init 会创建扩展 Ultracite 预设的配置：

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

// eslint.config.mjs — arrays of flat configs, spread together
import core from "ultracite/eslint/core";
import react from "ultracite/eslint/react";
export default [...core, ...react];

// oxlint.config.ts — imports passed to extends
import { defineConfig } from "oxlint";
import core from "ultracite/oxlint/core";
export default defineConfig({
  env: core.env,
  extends: [core],
  ignorePatterns: core.ignorePatterns,
});

各 linter 可用的预设（ultracite/<linter>/<preset>）：core、react、next、solid、vue、svelte、qwik、remix、tanstack、angular、astro、nestjs、jest、vitest、cypress、storybook、playwright、react-native、drizzle（cypress 和 storybook 仅在 ESLint 中有规则，playwright、react-native 和 drizzle 仅在 ESLint 和 Biome 中有规则；在其他 linter 中，它们不会添加插件规则）。ESLint 和 Biome 还提供 type-aware，其中包含需要类型信息的规则；ESLint 还提供适用于 angular、jest、nestjs、qwik、tanstack 和 vitest 的 <framework>/type-aware 扩展，应在对应框架的预设之后扩展。Oxlint 还提供 js-plugins（eslint-plugin-github、eslint-plugin-sonarjs 和 oxlint-plugin-react-doctor 通过 Oxlint 的 JS 插件支持运行；next/js-plugins 和 tanstack/js-plugins 会添加框架专用的 React Doctor 规则）、anti-slop 和 shadcn。这些都需要选择启用：只有在 init 提示中选中或通过 --js-plugins 传入时，init 才会添加它们。Oxlint 和 ESLint 还提供 gdp，适用于使用 gdp-ts 授权证明的代码库（@gdp-ts/core 自带该插件）；init 不会添加它，因此请在 core 之后手动扩展它。

迁移现有项目

迁移是指将项目自身的 ESLint、Prettier、Stylelint、Biome 或 Oxlint 配置切换为 Ultracite 预设；项目可以保留自己的代码检查工具。运行 init（它会预选检测到的代码检查工具），在 Ultracite 预设之后添加预设未涵盖的规则，并运行 ultracite fix，在一次提交中格式化所有内容。然后修复 check 仍然报告的问题，或者逐步迁移：

• 在 Ultracite 预设之后关闭每条失败的规则：对于 Oxlint，在 rules 中关闭（ultracite check -f json 会以 plugin(rule) 的形式列出这些规则，写作 plugin/rule）；对于 Biome，在 linter.rules 和 assist.actions.source 中关闭（使用 ultracite check --reporter=summary）。对于 ESLint，ultracite check --suppress-all 会将当前的错误记录到 eslint-suppressions.json 中。
• 每次重新启用少量规则：移除覆盖配置（或使用 ultracite check --prune-suppressions 清理抑制项），运行 ultracite fix，然后修复其余问题，每次变更处理一条规则。

完整步骤：https://www.ultracite.ai/docs/migrate.md

升级

npx ultracite@latest upgrade

upgrade 会安装最新版本的 Ultracite（或 --version 7 指定的版本），按该版本支持的版本重新安装代码检查工具，并运行 doctor。主要版本也会改变配置形式；upgrade 会列出项目仍需遵循的升级指南，使用 --claude 或 --codex 时，它会让相应的 Agent CLI 应用这些指南。

如需自行应用，请按顺序遵循所有适用的指南，从最早的开始。每份指南都会说明如何判断项目是否需要升级：

• references/upgrades/v5.md：将 Biome 1 的配置格式升级为 Biome 2 的格式
• references/upgrades/v6.md：将单个 ultracite 预设升级为 ultracite/core 加框架预设
• references/upgrades/v7.md：将 ultracite/<preset> 升级为 ultracite/biome/<preset>，并将 lint 和 format 命令升级为 check 和 fix
• references/upgrades/v8.md：从 ESLint 和 Stylelint 配置中移除 prettier/prettier、Cypress 和 Storybook 预设、设置类型检查规则的 ESLint 配置、Oxlint 的 typeAware 选项、init --yes，以及 ESLint 中 Zed 的格式化程序

代码规范

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

关键规则一览：

格式化由项目配置的代码检查工具／格式化程序处理。请遵循仓库现有的格式化设置，不要强制使用固定的行宽、引号样式或尾随逗号策略。

类型安全： 在有助于提高清晰度时使用显式类型。优先使用 unknown 而非 any。使用 as const 表示不可变值，并依靠类型收窄，而不是草率断言。

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

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

React 与无障碍访问： 使用函数组件，将 Hook 保持在顶层并确保依赖项正确，避免嵌套定义组件，并使用语义化 HTML 以及恰当的标签、标题、替代文本和键盘操作支持。

组织、安全、性能与测试： 保持函数职责单一，优先提前返回，避免使用 dangerouslySetInnerHTML 和 eval()，优先使用特定导入和顶层正则表达式，并确保测试中不包含 .only 和 .skip。

故障排除

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

1. Linter 和格式化工具的安装情况（Biome；或 ESLint + Prettier + Stylelint；或 Oxlint + oxfmt）
2. 配置有效性（是否正确继承 ultracite 预设）
3. package.json 依赖项中是否包含 Ultracite
4. 未使用 ESLint 后端时是否存在冲突工具（旧版 .eslintrc.* 文件、.prettierrc.*/prettier.config.*）

常见修复方法：

• 配置冲突：迁移到 Oxlint 或 Biome 后，删除遗留的 .eslintrc.* 和 .prettierrc.* 文件。使用 ESLint 时，.eslintrc.* 文件不会生效（ESLint 10 只读取 eslint.config.*），而 .prettierrc.* 是格式化工具的配置，因此两者都不会造成冲突
• 缺少依赖项：再次运行 bunx ultracite init，或手动将 ultracite 添加到 devDependencies
• 规则未生效：确保配置文件继承了适用于你所用框架的预设