ultracite

Ultracite

零設定的 JS/TS 專案 lint 與格式化。支援三種 linter 後端：Biome（建議）、ESLint + Prettier + Stylelint，以及 Oxlint + Oxfmt。

偵測 Ultracite

檢查 package.json 的 dependencies 或 devDependencies 中是否有 ultracite。透過以下方式偵測啟用的 linter（從目前目錄向上搜尋）：

• 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。未知選項會傳遞給底層 linter（例如 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 個 agent）
• --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 — 啟用型別感知 lint（Biome：擴充 type-aware 預設集；Oxlint：安裝 oxlint-tsgolint）
• --install-skill — 設定完成後安裝可重複使用的 Ultracite skill
• --skip-install — 跳過相依套件安裝
• --quiet — 抑制提示（當 CI=true 時自動偵測）

Init 會建立擴充 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,
});

每個 linter 可用的預設集（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。

重點規則一覽：

格式化由專案設定的 linter/formatter 處理。請尊重儲存庫現有的格式化設定，不要強制指定固定的行寬、引號樣式或尾逗號策略。

型別安全： 當型別有助於提升清晰度時，使用明確型別。優先使用 unknown 而非 any。對不可變值使用 as const，並依賴型別縮小而非粗暴的斷言。

現代 JavaScript/TypeScript： 優先使用 const、解構賦值、可選鏈、空值合併運算子、模板字串、for...of 和簡潔的箭頭函式。

非同步與正確性： 在 async 函式中務必 await promise。優先使用 async/await 而非 promise 鏈。從正式環境程式碼中移除 console.log、debugger 和 alert。

React 與無障礙： 使用函式元件，保持 hooks 在頂層並有正確的依賴，避免巢狀元件定義，並使用語義化 HTML 搭配正確的標籤、標題、替代文字和鍵盤操作。

組織、安全性、效能與測試： 保持函式專注，優先使用早期回傳，避免 dangerouslySetInnerHTML 和 eval()，優先使用特定匯入和頂層正規表達式，並確保測試中沒有 .only 和 .skip。

排解問題

執行 bunx ultracite doctor 進行診斷。它會檢查：

1. Linter 和 formatter 安裝（Biome；或 ESLint + Prettier + Stylelint；或 Oxlint + oxfmt）
2. 設定有效性（正確擴充 ultracite 預設集）
3. package.json 相依套件中的 Ultracite
4. 衝突工具（舊版 .eslintrc.* 檔案；未使用 ESLint 後端時的 .prettierrc.*/prettier.config.*）

常見修正：

• 衝突設定：遷移到 Ultracite 後刪除舊版 .eslintrc.* 和 .prettierrc.* 檔案
• 缺少相依套件：再次執行 bunx ultracite init 或手動將 ultracite 加入 devDependencies
• 規則未生效：確保設定檔為你的框架擴充了正確的預設集