shared-tooling-biome

Biome

クイックガイド： Biome は、JavaScript、TypeScript、JSX、TSX、JSON、CSS、GraphQL に対応した、統合型のリンター、フォーマッター、インポート整理ツールです。単一の Rust バイナリで ESLint + Prettier を置き換え、Prettier との互換性は 97％です。すべての設定には biome.json を使用します。biome check --write を実行すると、リンティング、フォーマット、インポート整理を一度に行えます。パイプラインでは biome ci を使用してください。

現在の安定版： Biome v2.4.x（2026年3月）。Biome v2 では、型を考慮したリンティング、ネストされた設定、刷新されたインポート整理機能が導入されました。

---

<critical_requirements>

重要：このスキルを使用する前に

（すべての設定には必ず biome.json または biome.jsonc を使用してください。Biome は JavaScript の設定ファイルを使用しません）

（Biome のフォーマットはバージョン間で変わる可能性があるため、必ず --save-exact を指定して正確なバージョンを固定してください）

（CI パイプラインでは必ず biome ci を使用してください。biome check は使用しないでください。ci は読み取り専用で、--write フラグはありません）

（ローカル開発では必ず biome check --write を使用してください。リンター、フォーマッター、インポート整理ツールを一度に実行します）

（エディターの自動補完と検証のため、必ず biome.json に $schema を含めてください）

</critical_requirements>

---

自動検出： Biome、biome.json、biome.jsonc、@biomejs/biome、biome check、biome lint、biome format、biome ci、biome-ignore、organizeImports、biome migrate

使用する場面：

• JavaScript／TypeScript プロジェクトに統合型リンターとフォーマッターを導入する
• ESLint + Prettier を、より高速な単一のツールに置き換える
• ゼロ設定または最小限の設定で始めたい新規プロジェクト
• リンティング／フォーマットの速度が重要な大規模コードベース
• 独自のグループ順序でインポート整理を設定する
• ESLint や Prettier から Biome に移行する
• biome ci を使った CI パイプラインを設定する
• Biome の --staged フラグを使ってコミット前フックを設定する

使用しない場面：

• Biome に相当する機能がない ESLint プラグインが必要なプロジェクト（例：フレームワーク固有のカスタムプラグイン）
• 再現できないカスタム ESLint ルールを多く利用しているプロジェクト
• Markdown、YAML、TOML のフォーマットが必要なプロジェクト（Biome はまだこれらに対応していません）
• ランタイムコード（これはビルド時のツールのみです）
• Git フックのフレームワーク設定（Husky／Lefthook の設定は別の事項です）
• TypeScript コンパイラーの設定（tsconfig.json の設定は別の事項です）

主な内容：

• フォーマッター、リンター、アシストの設定を含む biome.json の構成
• リンタールールのグループ（recommended、all、nursery）と重大度レベル
• フォーマッターの設定（インデントスタイル、行幅、引用符、セミコロン）
• 独自のグループ順序でのインポート整理
• CLI コマンド：check、format、lint、ci、migrate
• ESLint + Prettier からの移行
• Git フックとの連携（Husky、Lefthook、--staged フラグ）
• GitHub Actions と GitLab CI との CI 連携
• エディターとの連携（VS Code、JetBrains）
• 抑制コメント（biome-ignore、biome-ignore-all、範囲指定の抑制）
• モノレポ向けのネストされた設定
• ファイルごとの設定に対するオーバーライド

---

例

• セットアップと設定 — インストール、biome.json、VS Code、モノレポ、フレームワークの設定
• リンティングルール — ルールグループ、ドメイン、抑制、オーバーライド、インポートの順序
• フォーマット — フォーマッターのオプション、Prettier との互換性、オプションの対応付け
• CI と Git フック — GitHub Actions、GitLab CI、Husky、Lefthook、ステージ済みファイル
• ESLint／Prettier からの移行 — 自動移行、ルールの対応付け、パッケージの整理

その他のリソース：

• CLI クイックリファレンス — すべての CLI コマンド、フラグ、設定オプションの一覧

---

## Philosophy

Biome は、リンティング、フォーマット、インポートの整理を単一の設定ファイルを備えた単一のツールに統合します。Rust で構築されており、ESLint + Prettier より 20 倍高速なパフォーマンスを実現しながら、Prettier との互換性を 97% 維持します。

基本原則：

1. ツールは 1 つ、設定も 1 つ — biome.json が .eslintrc、prettier.config、インポート並べ替えプラグインに置き換わります
2. 妥当なデフォルト設定 — Biome は推奨ルールが有効な状態ですぐに使えます。設定なしでの使用も有効な選択肢です
3. 速度を機能として重視 — Rust 製のバイナリにより、大規模なコードベースも数秒ではなく数ミリ秒で処理できます
4. コマンドを統合 — biome check --write を実行すると、1 回の処理ですべてを実行できます（リンティング + フォーマット + インポートの整理）
5. デフォルトで安全 — 安全な修正は自動的に適用されます。安全でない修正には明示的な --unsafe フラグが必要です

---

基本パターン

パターン 1：基本的な biome.json 設定

Biome プロジェクトは、プロジェクトのルートにある biome.json から始まります。biome init でひな形を作成し、カスタマイズしてください。

# Install Biome (always pin exact version)
npm install --save-dev --save-exact @biomejs/biome

# Create default biome.json
npx @biomejs/biome init

// biome.json — minimal recommended setup
{
  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
  "linter": { "rules": { "recommended": true } },
  "assist": {
    "enabled": true,
    "actions": { "source": { "organizeImports": "on" } },
  },
}

良い理由： $schema によりエディターの自動補完が有効になり、VCS 連携によって .gitignore が尊重されます。indentStyle: "space" を明示することで、Biome のデフォルトであるタブを避けられます。推奨ルールによって、堅実な基盤を整えられます

// BAD: No schema, no VCS, relying on defaults that differ from Prettier
{ "linter": { "enabled": true } }

悪い理由： $schema がないと自動補完が失われ、VCS がないと node_modules もリンティングされます。また、Biome はデフォルトでタブを使用するため、Prettier からの移行時に戸惑うことがあります

完全な例： オーバーライド、フレームワーク設定、モノレポのセットアップを含む、本番環境向けの biome.json については、examples/core.md を参照してください。

---

パターン 2：リンタールールの設定

Biome は 8 つのグループ（accessibility、complexity、correctness、nursery、performance、security、style、suspicious）にわたる 459 以上のルールを提供します。ルールはデフォルトで recommended に設定され、安全で安定したルールの中から厳選されたものが有効になります。重大度レベルは "off"、"on"、"info"、"warn"、"error" です。ルールグループと重大度の一覧については、reference.md を参照してください。

ドメイン（テクノロジー固有のルール）

Biome v2 では、テクノロジーごとにルールをグループ化するドメインが導入されました。ドメインは package.json の依存関係から自動検出されます。

{ "linter": { "domains": { "react": "recommended", "test": "recommended" } } }

完全な例： ルール設定、抑制、オーバーライド、インポートの並べ替えについては、examples/linting.md を参照してください。

---

パターン 3：フォーマッターの設定

Biome のフォーマッターは Prettier との互換性を 97% 実現しています。グローバル設定はすべての言語に適用され、言語固有の設定はグローバル設定を上書きします。Biome はデフォルトでタブを使用します。Prettier から移行する場合は、indentStyle: "space" を明示的に設定してください。

{
  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
  "javascript": {
    "formatter": { "quoteStyle": "double", "semicolons": "always" },
  },
  "json": { "formatter": { "trailingCommas": "none" } },
  "css": { "formatter": { "enabled": true } },
}

完全なリファレンス： すべてのオプション、Prettier との対応、言語固有の設定については、examples/formatting.md を参照してください。

---

パターン 4：インポートオーガナイザー

Biome v2 では、カスタムのグループ順序に対応するようインポートオーガナイザーが刷新されました。assist.actions.source.organizeImports の下で設定します。

{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              [":BUN:", ":NODE:"],
              ":PACKAGE:",
              ":BLANK_LINE:",
              ["@company/**"],
              ":BLANK_LINE:",
              ":ALIAS:",
              ":PATH:",
              ":BLANK_LINE:",
              { "type": true },
            ],
            "identifierOrder": "natural",
          },
        },
      },
    },
  },
}

主なオプション： identifierOrder は名前付きインポートの並べ替えを制御します。"natural"（デフォルト。例：var1, var2, var11）または "lexicographic"（厳密なアルファベット順）を指定できます。グループには、定義済みマッチャー、glob パターン（"@my/lib/**"）、オブジェクトマッチャー（{ "type": true, "source": ["@my/lib"] }）、またはこれらを組み合わせた配列を指定できます。

事前定義済みグループ

グループ	一致する対象
:NODE:	Node.js の組み込みモジュールと node: プロトコル
:BUN:	Bun 固有のモジュール
:PACKAGE:	スコープ付きおよび通常の npm パッケージ
:PACKAGE_WITH_PROTOCOL:	プロトコルプレフィックス付きのパッケージ
:ALIAS:	エイリアス付きインポート（@/、#、~、$、%）
:PATH:	絶対パスおよび相対パスのインポート
:URL:	HTTP/HTTPS のインポート
:BLANK_LINE:	グループ間の視覚的な区切り

完全な例： 結果付きのインポート順序については、examples/linting.md を参照してください。

---

パターン 5：CLI コマンド

ローカルでは check、パイプラインでは ci を使用します。主なコマンド：

npx biome check --write .          # Lint + format + organize imports (auto-fix)
npx biome ci .                     # CI mode (read-only, optimized for pipelines)
npx biome check --staged --write . # Pre-commit hooks (only staged files)
npx biome check --changed --since=main .  # Changed files only

完全なリファレンス： CLI の使用方法、フィルタリング、レポートのオプションについては、examples/ci.md を参照してください。

---

パターン 6：抑制コメント

Biome では、説明が必須の biome-ignore コメントを使用します。

// biome-ignore lint/suspicious/noDebugger: needed for local debugging
debugger;

// biome-ignore-all lint/style/noDefaultExport: framework requires default export (top of file only)

// biome-ignore-start lint/suspicious/noDoubleEquals: legacy section
// biome-ignore-end lint/suspicious/noDoubleEquals: legacy section

抑制構文の完全な表と指定子のレベルについては、reference.md を参照してください。インライン、ファイル単位、範囲指定の抑制例については、examples/linting.md を参照してください。

---

パターン 7：ネストされた設定（モノレポ）

Biome v2 はネストされた biome.json ファイルをサポートしています。各サブディレクトリでは、ルート設定を上書きできます。

// packages/my-app/biome.json — inherits from root
{ "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json", "extends": "//" }

// packages/legacy-lib/biome.json — relaxes rules
{
  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
  "root": false,
  "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } },
}

適切な理由： "extends": "//" の省略形でルート設定を継承し、"root": false で子設定として指定します。各パッケージでルールを個別に緩和または厳格化できます。

完全な例： ルート設定と子設定のパターンについては、examples/core.md を参照してください。

---

パターン 8：オーバーライド（ファイルごとのルール）

ネストされた設定ファイルを使わずに、ファイルパターンごとの設定を指定するには overrides を使用します。

{
  "overrides": [
    {
      "includes": ["**/*.test.ts", "**/*.test.tsx"],
      "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } },
    },
    {
      "includes": ["**/app/**/page.tsx", "**/app/**/layout.tsx"],
      "linter": { "rules": { "style": { "noDefaultExport": "off" } } },
    },
  ],
}

適切な理由： オーバーライドにより、すべてのファイルに抑制コメントを追加する必要がなくなります。テストファイルのルールを緩和でき、フレームワークの規約も宣言的に処理できます。

完全な例： テスト、設定、生成ファイルのオーバーライドについては、examples/linting.md を参照してください。

---

パフォーマンス

Biome は Rust で記述され、ファイルを並列処理するため、JavaScript ベースの代替ツールより大幅に高速です。

ツール	フォーマット時間（1000 ファイル）	リント時間（1000 ファイル）
Biome	~100ms	~200ms
Prettier	~2000ms	N/A
ESLint	N/A	~3000ms
ESLint + Prettier	~5000ms	~5000ms

概算ベンチマークです。実際のパフォーマンスは、プロジェクトの規模やルールの設定によって異なります。

パフォーマンスのヒント：

• biome format と biome lint を個別に実行する代わりに biome check を使用する — 一度の処理で済むため、より高速です
• VCS 統合を有効にすると、無視対象のファイル（.gitignore）が自動的にスキップされます
• フックや CI では --staged または --changed を使用すると、影響を受けたファイルのみを処理できます
• nursery ルールは選択して使用する — 一部の実験的なルールはパフォーマンスに影響する場合があります
• --profile-rules（v2.4+）を使用すると、設定内の処理が遅いリントルールを特定できます

型情報を考慮したリントのパフォーマンス：

Biome v2 では、TypeScript コンパイラーを使わずに型情報を考慮したリントが導入されました。必要に応じて有効にしてください。

• デフォルトのスキャンでは、ネストされた設定のみを検出します（高速）
• プロジェクトドメインのスキャンでは、モジュールグラフ全体をインデックス化します（低速ですが、tsc よりは高速です）
• types ドメインのスキャンでは、型推論が追加されます（最も網羅的で、最も処理コストが高くなります）

---

<decision_framework>

選択の指針

Biome と ESLint + Prettier の比較

Need linting and formatting?
|-- Greenfield project?
|   |-- Want simplest possible setup? -> Biome (one tool, one config)
|   |-- Need niche ESLint plugins? -> ESLint + Prettier
|   +-- Speed is important? -> Biome (20x faster)
|-- Existing ESLint + Prettier project?
|   |-- Happy with current setup? -> Stay with ESLint + Prettier
|   |-- Config complexity is a pain? -> Migrate to Biome
|   |-- Need ESLint plugins without Biome equivalents? -> Stay
|   +-- Want faster CI/pre-commit hooks? -> Biome (or hybrid)
+-- Monorepo?
    |-- Need per-package lint configs? -> Biome v2 nested configs or ESLint 10
    +-- Speed bottleneck in CI? -> Biome

設定の複雑さ

How to configure Biome?
|-- Just starting out? -> Run `biome init`, use defaults with recommended: true
|-- Migrating from ESLint? -> Run `biome migrate eslint --write`
|-- Migrating from Prettier? -> Run `biome migrate prettier --write`
|-- Need per-file rules?
|   |-- Different rules for test files? -> Use `overrides` in biome.json
|   +-- Different rules per package? -> Use nested biome.json with "root": false
+-- Need custom import ordering? -> Configure organizeImports.options.groups

完全な移行判断ツリー： examples/migration.md を参照してください。

</decision_framework>

---

統合ガイド

対応対象：

• JSX/TSX：React 固有の lint ルールに対応する react ドメインで、完全にサポートされています
• TypeScript：tsc への依存なしで、型を考慮した lint を実行できます（Biome v2+）
• CSS：lint はデフォルトで有効、フォーマットはオプトインです
• JSON/JSONC：tsconfig.json、package.json を含め、完全にサポートされています
• GraphQL：lint はデフォルトで有効、フォーマットはオプトインです
• Vue/Svelte/Astro：html.experimentalFullSupportEnabled による実験的なサポートです（v2.4+）

置き換え／競合するもの：

• ESLint：Biome は lint において ESLint を置き換えます（またはハイブリッド方式を使用してください）
• Prettier：Biome はフォーマットにおいて Prettier を置き換えます
• eslint-plugin-import：Biome の import オーガナイザーが import ソート用プラグインを置き換えます
• eslint-config-prettier：不要です — Biome にはフォーマッターと linter の競合がありません

CI／エディターとの統合： examples/ci.md および examples/core.md を参照してください。

---

<red_flags>

要注意事項

優先度の高い問題：

• CI で biome ci ではなく biome check を使用する（check は --write を許可するため、パイプラインでは危険です。ci は読み取り専用です）
• Biome のバージョンを --save-exact で固定していない（マイナーバージョン間でフォーマットが変わる可能性があり、差分が増える原因になります）
• biome.json に $schema がない（エディターの自動補完、検証、設定の見つけやすさが損なわれます）
• biome.json ではなく JavaScript の設定ファイルを使用する（Biome がサポートする設定形式は JSON/JSONC のみです）
• biome check で両方を実行できるのに、biome format と biome lint を別々に実行する（時間を無駄にし、ファイルを2回解析します）

優先度が中程度の問題：

• Prettier から移行する際に indentStyle: "space" の設定を忘れる（Biome のデフォルトはタブです）
• VCS 統合を有効にしていない（有効にしないと、Biome が node_modules や dist を処理する可能性があります）
• 変更内容を確認せずに --unsafe を使用する（安全でない修正はプログラムの動作を変える可能性があります）
• git フックに --no-errors-on-unmatched を含めていない（ステージされたファイルに一致するものがない場合に失敗します）
• nursery ルールをすべて有効にする（実験的なルールであり、バグやパフォーマンスの問題がある可能性があります）

よくある間違い：

• ネストした設定で "root": true を使用する（これはデフォルトです。子設定には "root": false を使用してください）
• Markdown/YAML のフォーマットに対応していると思い込む（Biome はこれらの言語をまだサポートしていません）
• メジャーバージョンをアップグレードする際に biome migrate --write を実行しない（v1 と v2 の間では設定スキーマが変わります）
• 説明のない抑制コメントを使用する（biome-ignore lint: のコロンの後にはテキストが必要です）

注意点とエッジケース：

• Biome のデフォルトはスペースではなくタブです — Prettier から移行する際は、必ず indentStyle を明示的に設定してください
• CSS と GraphQL のフォーマットはデフォルトで無効です — "formatter": { "enabled": true } でオプトインする必要があります
• biome-ignore-all はファイルの先頭に置く必要があります — ファイルの途中に置くと、未使用の抑制に関する警告が発生します
• import オーガナイザーは linter ではなく assist の一部です — assist.actions.source.organizeImports の下で設定してください
• --staged フラグを使えば、Biome のみの構成では lint-staged が不要になります（Biome v1.7.0+）
• 型を考慮した lint（project/types ドメイン）はファイルのスキャンを引き起こすため、大規模なプロジェクトでは初回実行に時間がかかることがあります
• biome migrate eslint --write は、デフォルトでは派生ルールを移行しません — それらを含めるには --include-inspired を使用してください
• 範囲指定の抑制（biome-ignore-start/biome-ignore-end）には、一致するルール指定子が必要です
• Biome は javascript 設定キーの下で、すべての JS/TS/JSX/TSX を扱います — 個別の typescript セクションはありません
• .biome.json（先頭にドットが付く）という名前の設定ファイルも検出されます（v2.4+）

</red_flags>

---

<critical_reminders>

重要な注意事項

（すべての設定には、必ず biome.json または biome.jsonc を使用してください。Biome は JavaScript 設定ファイルを使用しません）

（Biome は --save-exact を指定して、必ず正確なバージョンに固定してください。Biome のフォーマット結果はバージョン間で変わることがあります）

（CI パイプラインでは、必ず biome check ではなく biome ci を使用してください。ci は読み取り専用で、--write フラグはありません）

（ローカル開発では、必ず biome check --write を使用してください。リンター、フォーマッター、インポートオーガナイザーを一度に実行します）

（エディターの自動補完と検証のため、biome.json に必ず $schema を含めてください）

これらのルールに従わないと、フォーマットの不一致、CI パイプラインの破損、リンターエラーの見落としが発生します。