ultracite

Ultracite

JS/TS プロジェクト向けの、設定不要のリンティングとフォーマットです。3 つのリンターバックエンドに対応しています。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 は、各エージェントがルールを読み込むために必要なインポート、設定、またはコピーも追加します。codex、copilot、cline、amp、cursor-cli などの ID（40 個のエージェントに対応）は、それ以外の作業は不要です
• --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 — 型情報を利用したリントを有効にします（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,
});

各リンターで利用できるプリセット（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 のみです。他のリンターではプラグインルールは追加されません）。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 で渡した場合にのみ追加します。Oxlint と ESLint には、gdp-ts の認可証明を使用するコードベース向けの gdp もあります（@gdp-ts/core にプラグインが含まれています）。init はこれを追加しないため、core の後に手動で拡張してください。

既存プロジェクトの移行

移行とは、プロジェクト独自の ESLint、Prettier、Stylelint、Biome、または Oxlint の設定を Ultracite のプリセットに切り替えることです。プロジェクトでは、引き続き同じリンターを使用できます。init を実行すると、検出されたリンターがあらかじめ選択されます。Ultracite のプリセットでカバーされないルールは、Ultracite のプリセットの後に追加し、ultracite fix を実行して、すべてを 1 つのコミットでフォーマットします。その後、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 を実行して、残りを修正します。変更ごとにルールを 1 つずつ扱います。

詳しい手順：https://www.ultracite.ai/docs/migrate.md

アップグレード

npx ultracite@latest upgrade

upgrade は最新の Ultracite（または --version 7 で指定したリリース）をインストールし、そのリリースでサポートされるバージョンのリンターを再インストールして、doctor を実行します。メジャーリリースでは設定の形式も変わります。upgrade は、プロジェクトに必要なガイドを一覧表示します。また、--claude または --codex を指定すると、そのエージェント 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 を参照してください。

主なルールの概要：

フォーマットは、プロジェクトで設定されているリンター／フォーマッターが処理します。行幅、引用符のスタイル、末尾のカンマの方針を一律に強制するのではなく、リポジトリの既存のフォーマッター設定に従ってください。

型安全性： 明確さが増す場合は、明示的な型を使用してください。any より unknown を優先してください。不変値には as const を使用し、強引な型アサーションより型の絞り込みを活用してください。

モダンな JavaScript／TypeScript： const、分割代入、オプショナルチェーン、Null 合体演算子、テンプレートリテラル、for...of、簡潔なアロー関数を優先してください。

非同期処理と正確性： 非同期関数内では、常にプロミスに await を付けてください。プロミスチェーンより async/await を優先してください。本番コードから console.log、debugger、alert を削除してください。

React とアクセシビリティ： 関数コンポーネントを使用し、フックは適切な依存関係を指定してトップレベルに配置し、コンポーネントのネストした定義は避けてください。適切なラベル、見出し、代替テキスト、キーボード操作への対応を備えたセマンティック HTML を使用してください。

構成、セキュリティ、パフォーマンス、テスト： 関数の役割を明確にし、早期リターンを優先してください。dangerouslySetInnerHTML と eval() は避け、具体的なインポートとトップレベルの正規表現を優先してください。また、テストでは .only と .skip を使用しないでください。

トラブルシューティング

bunx ultracite doctor を実行して診断します。次の項目を確認します。

1. リンターとフォーマッターのインストール状況（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 に手動で追加してください
• ルールが適用されない：設定ファイルが、使用しているフレームワークに適したプリセットを拡張していることを確認してください