biome

Biome

JavaScript、TypeScript、JSX、CSS、GraphQL 向けの、高速で統合されたリンティング、フォーマット、インポート整理ツールです。Biome 2.4 は、TypeScript コンパイラーを使わない型認識リンティング、カスタムルール向けの GritQL プラグイン、ドメインベースのルールグループ化を提供します。単一バイナリで、デフォルトでは設定不要、Prettier との互換性は 97％です。

重要なルール

files.ignore は存在しません — 否定パターンを使って files.includes を指定してください

Biome 2.x がサポートするのは files.includes（末尾に s が付きます）のみです。files.ignore、files.include（s なし）、files.exclude は存在しません。これらを使うと、Found an unknown key エラーが発生します。

files 配下で有効なキーは、includes、maxSize、ignoreUnknown のみです。（experimentalScannerIgnores は存在しますが、上流ドキュメントでは現在非推奨とされており、削除される可能性があります。）

生成コードやベンダー提供ファイルなどを除外するには、files.includes で否定パターンを使います。

{
  "files": {
    "includes": ["**", "!**/routeTree.gen.ts", "!**/generated/**"]
  }
}

ほかのツールやアシストが処理する場合でもスキャナーにスキップさせる必要があるパスには、files.includes 内で !! の強制無視構文を使います（experimentalScannerIgnores の代わりです）。

{
  "files": {
    "includes": ["**", "!!**/legacy-vendor/**"]
  }
}

生成ファイルをスキップするために、overrides で linter/formatter/assists: { enabled: false } を使わないでください。この方法は脆弱で（アシストやインポートオーガナイザーなどのサブシステムを見落としやすく）、不必要に複雑です。files.includes で除外してください。

個別に lint と format を実行せず、常に biome check を使ってください

biome check は、フォーマッター、リンター、インポートオーガナイザーをまとめて実行します。CI で biome lint と biome format を個別に呼び出さず、biome check（または CI モードの biome ci）を使ってください。

biome.json はプロジェクトのルートに置きます

各プロジェクトには、ルートに biome.json が 1 つ必要です。モノレポのパッケージでは、ルートの設定を継承するために "extends": "//" を指定したネストされた設定を使います。"extends": ["../../biome.json"] のような相対パスは使わないでください。

修正を適用するには --write を使います

biome check --write .            # Apply safe fixes only
biome check --write --unsafe .   # Apply all fixes including unsafe (review changes)

biome lint と biome format では --fix が --write の別名として使えますが、標準のエントリーポイントは biome check であり、ドキュメントで案内されているフラグは --write です。--write を使ってください。

安全な修正と安全でない修正。 未使用のインポート、パラメーター、変数の削除は、外部の呼び出し元がそのシンボルを参照している可能性があるため、安全でない修正に分類されます。通常の --write では削除されず、診断が報告されます。--write --unsafe を使う（差分を確認してください）か、手動で削除してください。

バージョンを正確に固定し、アップグレード後にマイグレーションを実行します

pnpm add --save-dev --save-exact @biomejs/biome@latest
pnpm biome migrate --write

biome.json の $schema URL にはバージョンが固定されています（例："$schema": "https://biomejs.dev/schemas/2.4.13/schema.json"）。@biomejs/biome のバージョンを上げると、biome migrate --write を実行するまで、CLI は The configuration schema version does not match the CLI version というエラーを出します。後回しにせず、アップグレードの一環として実行してください。

クイックスタート

pnpm add --save-dev --save-exact @biomejs/biome
pnpm biome init    # Creates default biome.json with recommended rules

IDE の設定

VS Code — biomejs.biome 拡張機能をインストールします。

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

source.fixAll.biome は保存時に安全な lint 修正を適用し、source.organizeImports.biome はアシストを実行します。CLI の biome check --write と同等にするには、両方が必要です。

Zed — Biome 拡張機能が標準で利用できます。インライン設定機能（v2.4）を使うと、biome.json に影響を与えずにエディターからルールを上書きできます。表記に注意してください。Zed では inline_config（スネークケース）、VS Code 拡張機能では inlineConfig（キャメルケース）を使います。

{
  "formatter": { "language_server": { "name": "biome" } },
  "lsp": {
    "biome": {
      "settings": {
        "inline_config": {
          "linter": { "rules": { "suspicious": { "noConsole": "off" } } }
        }
      }
    }
  }
}

CI との統合

pnpm biome ci .                                  # No writes, non-zero exit on errors
pnpm biome ci --reporter=default --reporter=github .  # GitHub Actions annotations

設定（biome.json）

React／TypeScript プロジェクト向けの推奨設定

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "includes": [
      "src/**/*.ts", "src/**/*.tsx",
      "tests/**/*.ts", "**/*.config.ts", "**/*.json",
      "!**/generated", "!**/components/ui"
    ]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 120
  },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true },
    "domains": { "react": "recommended" }
  },
  "javascript": {
    "formatter": { "quoteStyle": "double" }
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": { "organizeImports": "on" }
    }
  }
}

フォーマッターのオプション

主なオプション：indentStyle（"space"／"tab"）、indentWidth、lineWidth、lineEnding（"lf"／"crlf"）、trailingNewline。JavaScript 固有のオプション：quoteStyle、trailingCommas、semicolons、arrowParentheses、bracketSpacing。

リンターのルール設定

ルールでは、"error"、"warn"、"info"、"off" の重大度レベルを使います。一部のルールではオプションも指定できます。

{
  "linter": {
    "rules": {
      "recommended": true,
      "style": {
        "noRestrictedGlobals": {
          "level": "error",
          "options": {
            "deniedGlobals": {
              "Buffer": "Use Uint8Array for browser compatibility."
            }
          }
        },
        "useComponentExportOnlyModules": "off"
      }
    }
  }
}

インポートの整理

インポート整理機能（Biome Assist）は、重複を統合し、距離順に並べ替え、カスタムグループ分けに対応します。v2.4.13 以降は、TypeScript モジュール（module "x" { ... }）内のインポートと .d.ts 宣言ファイル内のインポートも並べ替えます。

{
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              { "source": "builtin" },
              { "source": "external" },
              { "source": "internal", "match": "@company/*" },
              { "source": "relative" }
            ]
          }
        }
      }
    }
  }
}

サブシステムごとの includes

各サブシステム（linter、formatter、assist）には、細かく対象範囲を指定するための独自の includes があります。files.includes の後に適用され、対象範囲を狭めることはできますが、広げることはできません。

{
  "files": {
    "includes": ["**", "!**/dist"]
  },
  "linter": {
    "includes": ["**", "!**/components/ui"]
  },
  "formatter": {
    "includes": ["**", "!**/components/ui"]
  }
}

これにより、dist/ と components/ui を除くすべてをリントおよびフォーマットしながら、アシスト（インポート整理）は引き続き components/ui でも実行されます。

オーバーライド

オーバーライドを使うと、特定のファイルパターンに異なる設定を適用できます。ファイルごとのルール調整（例：ベンダー提供のコンポーネントや shadcn コンポーネントでルールを緩和する場合）に使用します。フィールド名は includes（末尾に s が付きます）です。

{
  "overrides": [
    {
      "includes": ["**/components/ui/**"],
      "linter": {
        "rules": {
          "suspicious": { "noDocumentCookie": "off" },
          "style": { "useComponentExportOnlyModules": "off" }
        }
      }
    },
    {
      "includes": ["**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": { "noConsole": "off" }
        }
      }
    }
  ]
}

モノレポの設定

ルートの biome.json に共有設定を記述します。パッケージの設定は "extends": "//" で継承します。

{
  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
  "extends": "//"
}

"extends": "//" と並べて linter.rules セクションを追加すると、パッケージごとに特定のルールをオーバーライドできます。

設定ファイルの検出（v2.4）

検索順序：biome.json -> biome.jsonc -> .biome.json -> .biome.jsonc -> プラットフォームの設定ホーム。

プラットフォーム別の設定ホームのパス：

プラットフォーム	パス
Linux	$XDG_CONFIG_HOME/biome（または ~/.config/biome）
macOS	~/Library/Application Support/biome
Windows	%APPDATA%\biome\config（つまり C:\Users\<user>\AppData\Roaming\biome\config）

v2.4 のその他の注目点

• 埋め込みスニペット：Biome 2.4 は、JavaScript 内に埋め込まれた CSS と GraphQL（例：styled-components、Emotion、gql テンプレートリテラル）をフォーマットおよびリントします。自動的に機能するため、追加の設定は不要です。
• Vue/Svelte パーサーの改善：.vue および .svelte ファイル内の noUnusedVariables、useConst、useImportType、noUnusedImports で誤検知が大幅に減少しました。

ドメイン

ドメインはテクノロジーごとにリントルールをまとめます。スタックに必要なものだけを有効にしてください。

{
  "linter": {
    "domains": {
      "react": "recommended",
      "next": "recommended",
      "test": "recommended",
      "types": "all"
    }
  }
}

ドメイン	目的	自動検出
react	React フック、JSX パターン	react >= 16.0.0
reactNative	React Native のルール（noReactNativeRawText、noReactNativeLiteralColors、noReactNativeDeepImports、useReactNativePlatformComponents）	react-native
next	Next.js 固有のルール	next >= 14.0.0
solid	Solid.js のルール	solid-js の依存関係
qwik	Qwik 固有のルール	@builder.io/qwik
vue	Vue 固有のルール	vue
test	テストのベストプラクティス（あらゆるフレームワーク）	jest、mocha、ava、または vitest
playwright	Playwright のテストルール	@playwright/test
drizzle	Drizzle ORM の安全性ルール	drizzle-orm
turborepo	Turborepo のモノレポルール	turbo
project	ファイル横断の解析（noImportCycles、noUnresolvedImports）	-
types	型推論のルール（noFloatingPromises、noMisusedPromises）	-

有効化レベル： "recommended"（安定したルールのみ）、"all"（nursery を含む）、"none"（無効化）。

project ドメインを有効にすると、モジュールグラフを必要とするルールが有効になります。types ドメイン（v2.4）を有効にすると、型推論を必要とするルールが有効になります。どちらもファイルスキャンを実行するため、わずかなオーバーヘッドが発生します。

型を考慮したリント

Biome 2.0 では、TypeScript コンパイラーを使わずに型を考慮したリントが導入されました。Biome は Rust で独自の型推論エンジンを備えているため、typescript 依存関係は不要です。

仕組み

types ドメインを有効にして、ファイルスキャンと型推論を有効化します。推論はネイティブに実行されるため、パフォーマンスへの影響は typescript-eslint と比べて最小限です。

v2.4.12 の改善点： 型を考慮したルールが、Pick<T, K>、Omit<T, K>、Partial<T>、Required<T>、Readonly<T> のユーティリティ型を通じてメンバーを解決するようになりました（optional、readonly、および nullable のフラグを保持します）。これにより、ルールはコードと同じ形状を認識できます。

主なルール

ルール	検出する問題
noFloatingPromises	処理されていない Promise（await／return／void の指定漏れ）
noMisusedPromises	条件式や配列コールバック内の Promise
useAwaitThenable	thenable ではない値への await
noUnnecessaryConditions	常に true／false となる条件
useRegexpExec	regexp.exec() のほうが適切な string.match()
useFind	array.find() ではなく array.filter()[0] を使用
useArraySortCompare	比較関数を指定していない Array.sort()

noFloatingPromises

型を考慮するルールの中で最も効果的なルールです。処理されていない Promise を検出します。

// ERROR: floating promise
async function loadData() {
  fetch("/api/data");
}

// VALID: awaited
async function loadData() {
  await fetch("/api/data");
}

// VALID: explicitly voided (fire-and-forget)
async function loadData() {
  void fetch("/api/data");
}

typescript-eslint と比較して約 75％のケースを検出し、リリースごとに改善しています。v2.4.12 では、モジュールをまたぐジェネリックラッパー関数（別ファイルから再エクスポートされたジェネリックな wrap(fn) など）を介した検出が追加されました。

React Compiler と useExhaustiveDependencies の併用

React Compiler を使用している場合、useExhaustiveDependencies は、コンパイラーがメモ化を処理していることを認識できません。React Compiler の多くのユーザー（Biome のコントリビューターを含む）は、このルールを完全に無効にしています。

{
  "linter": {
    "rules": {
      "correctness": {
        "useExhaustiveDependencies": "off"
      }
    }
  }
}

このルールを有効にしたままにする場合、値に意図的に依存しているものの、本文内では読み取らないエフェクト（ナビゲーション時に再トリガーするための location.pathname など）を抑制する必要があります。

typescript-eslint と比べた制限事項

• 複雑なジェネリック型の推論では、一部のケースを検出できないことがあります
• 完全な型チェッカーではなく、一般的なパターンに対応しますが、すべてのエッジケースを網羅するわけではありません
• ルールはまだ nursery 段階のため、リリースごとに改善される見込みです
• 大きなパフォーマンス上の利点があります。tsc ベースの lint にかかる時間のごく一部で済みます

GritQL カスタムルール

GritQL は、カスタム lint ルール向けの宣言型パターンマッチング言語です。.grit ファイルを作成し、プラグインとして登録します。

{ "plugins": ["./lint-rules/no-object-assign.grit"] }

例

Object.assign の使用を禁止する：

`$fn($args)` where {
    $fn <: `Object.assign`,
    register_diagnostic(
        span = $fn,
        message = "Prefer object spread instead of `Object.assign()`"
    )
}

CSS - カラークラスを強制する：

language css;
`$selector { $props }` where {
    $props <: contains `color: $color` as $rule,
    not $selector <: r"\.color-.*",
    register_diagnostic(
        span = $rule,
        message = "Don't set explicit colors. Use `.color-*` classes instead."
    )
}

プラグイン API

register_diagnostic() の引数：

• severity - "hint"、"info"、"warn"、"error"（デフォルト："error"）
• message（必須）- 診断メッセージ
• span（必須）- ハイライトする構文ノード

サポート対象の言語：JavaScript（デフォルト）と CSS、および v2.4 以降の JSON（v2.4 のリリースブログでは JSON が追加されていますが、linter/plugins/ のリファレンスページには JS／CSS しか記載されていない場合があります。ブログの情報が優先されます）。biome lint --profile-rules . でルールとプラグインの実行をプロファイリングできます。

抑制パターン

1 行

// biome-ignore lint/suspicious/noConsole: needed for debugging
console.log("debug info");

ファイル単位

// biome-ignore-all lint/suspicious/noConsole: logger module

範囲指定

// biome-ignore-start lint/style/useConst: legacy code
let x = 1;
let y = 2;
// biome-ignore-end lint/style/useConst
const a = 4; // this line IS checked

biome-ignore-end は省略可能です。省略すると、ファイル末尾まで抑制されます。Biome では、コロンの後に説明文が必要です。

移行

ESLint からの移行

pnpm biome migrate eslint --write
pnpm biome migrate eslint --write --include-inspired  # Include non-identical rules

レガシー設定とフラット設定、extends の解決、プラグイン（typescript-eslint、react、jsx-a11y、unicorn）、.eslintignore に対応しています。

Prettier からの移行

pnpm biome migrate prettier --write

tabWidth -> indentWidth、useTabs -> indentStyle、singleQuote -> quoteStyle、trailingComma -> trailingCommas にマッピングします。

ESLint と Prettier の併用からの移行

pnpm biome migrate eslint --write
pnpm biome migrate prettier --write
pnpm remove eslint prettier eslint-config-prettier eslint-plugin-prettier \
  @typescript-eslint/parser @typescript-eslint/eslint-plugin
rm .eslintrc* .prettierrc* .eslintignore .prettierignore

ESLint はデフォルトで gitignore を尊重するため、VCS 統合を有効にします。

{ "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true } }

CLI リファレンス

biome check（主なコマンド）

biome check .                    # Check all files
biome check --write .            # Apply safe fixes
biome check --write --unsafe .   # Apply all fixes
biome check --changed .          # Only VCS-changed files
biome check --staged .           # Only staged files

biome ci（CI モード）

biome ci .                                           # No writes, exit code on errors
biome ci --reporter=github .                         # GitHub annotations
biome ci --reporter=sarif --reporter-file=report.sarif .  # SARIF output

biome lint

biome lint --only=suspicious/noDebugger .    # Single rule
biome lint --skip=project .                  # Skip domain
biome lint --only=types .                    # Only type-aware rules
biome lint --error-on-warnings .             # Warnings become errors
biome lint --enforce-assist .                # Fail when assist actions remain unapplied
biome lint --suppress --reason "tracked in #123" .  # Insert biome-ignore suppressions instead of fixes

--enforce-assist は CI で便利です。インポートの整理などの assist アクションはデフォルトでは lint 診断ではないため、単独の biome ci では、インポートの順序が正しくなくても成功する場合があります。--suppress を --reason と組み合わせると、biome-ignore コメントを一括追加できます（Biome では、コロンの後に説明文が必要です）。

その他のコマンド

biome format --write .                       # Format only
biome search '`console.$method($args)`' .    # GritQL pattern search
biome rage                                   # Debug info for bug reports
biome explain noFloatingPromises             # Explain a rule

ベストプラクティス

1. biome check を単一のコマンドとして使う - フォーマット、リント、インポートの整理をまとめて実行します
2. recommended: true から始める - 必要に応じて個別のルールを無効にします
3. 関連するドメインを有効にする - 使用するスタックに応じて react、next、test、types を有効にします
4. VCS 統合を有効にする - .gitignore を尊重し、--changed／--staged を使えるようにします
5. パイプラインでは biome ci を使う - ファイルへの書き込みは行わず、明確な終了コードを返します
6. バージョンを正確に固定する - リリース間で予期しないルールの変更が起きるのを防ぎます
7. アップグレードのたびに biome migrate --write を実行する
8. コミット前フックでは --staged を使う：biome check --staged --write --no-errors-on-unmatched .
9. 時間のかかるルールをプロファイリングする：biome lint --profile-rules（v2.4）
10. ルールを一律に無効化する代わりに、プロジェクト固有のパターンには GritQL プラグインを使う

注意点

ここに挙げるのは、設定の破損、作業ツリーの変更、デバッグ時間の浪費につながった実際のミスです。Biome の設定を作成する前にお読みください。

1. files.ignore、files.include、files.exclude は存在しません。 使えるのは files.includes（末尾に s が付くもの）だけです。それ以外を指定すると、Biome は Found an unknown key を出します。上記の最初の重要なルールを参照してください。

2. organizeImports はトップレベルの設定キーではありません。 Biome 2.x では assist.actions.source.organizeImports の下に移動しました。トップレベルに指定すると設定エラーになります。

3. linter と formatter を無効にする overrides でも、assist は実行されます。 overrides を使って生成ファイルをスキップしても、インポートオーガナイザー（assist アクション）はそのファイルを書き換えます。これにより、気づかないうちに作業ツリーが変更されます。ファイルを完全に除外するには、files.includes の否定を使ってください。

4. overrides フィールドは include ではなく includes（末尾に s が付くもの）です。 files.includes と同じ命名です。

5. biome check --write はフォーマッター、リンター、assist を一度に実行します。 これらのどれもがファイルを変更する可能性があります。check --write の実行後も生成ファイルが変更される場合は、どのサブシステムが変更しているかを確認してください。フォーマッターやリンターではなく、インポートオーガナイザー（assist）が原因であることがよくあります。

6. --fix より --write を優先する。 --fix は biome lint と biome format で --write の別名として文書化されていますが、正規のエントリーポイントは biome check であり、どのコマンドでも文書化されているフラグは --write です。--write を選び、一貫して使ってください。

7. package.json の無限再フォーマットループ。 Biome のデフォルトの JSON フォーマッターはタブを使いますが、pnpm（およびほかのいくつかのツール）は package.json を 2 スペースのインデントで書き込みます。インストールのたびにファイルが書き換えられ、その後 biome check --write が再び書き換えるため、コミットのたびに変更が発生します。package.json を除外する（files.includes に "!**/package.json" を指定する）か、JSON のインデントにスペースを使うようオーバーライドして修正してください。

   {
     "overrides": [
       {
         "includes": ["**/package.json"],
         "json": { "formatter": { "indentStyle": "space", "indentWidth": 2 } }
       }
     ]
   }
   

リソース

• Biome ドキュメント: https://biomejs.dev/
• Biome GitHub: https://github.com/biomejs/biome
• GritQL ドキュメント: https://docs.grit.io/
• Biome v2 ブログ: https://biomejs.dev/blog/biome-v2/
• Biome v2.4 ブログ: https://biomejs.dev/blog/biome-v2-4/
• 移行ガイド: https://biomejs.dev/guides/migrate-eslint-prettier/
• ルールリファレンス: https://biomejs.dev/linter/javascript/rules/
• ドメイン: https://biomejs.dev/linter/domains/
• プラグイン: https://biomejs.dev/linter/plugins/

カテゴリ別の詳細なリントルールとコード例については、rules-reference.md を参照してください。