knip

Knip によるコードのクリーンアップ

knip を実行して、このコードベース内の未使用ファイル、依存関係、エクスポートを見つけて削除します。

セットアップ

1. knip が利用可能か確認します。

   • npx knip --version を実行して確認します
   • 失敗する場合、または非常に時間がかかる場合は、package.json の devDependencies に knip があるか確認します
   • ローカルにインストールされていない場合は、存在するロックファイルに応じて npm install -D knip（または pnpm／yarn／bun に相当するコマンド）でインストールします

2. Knip はファイル内の未使用インポートや変数を削除しません。これはリンターの役割です。Knip はプロジェクト全体を対象に、未使用ファイル、依存関係、エクスポートを見つけます。

ワークフロー

必ず、まず設定を確認するこのワークフローに従ってください。「knip を実行」や「コードベースをクリーンアップ」といった単純な指示でも、報告された問題に対処する前に knip を適切に設定してください。

ステップ 1：プロジェクトを把握する

• プロジェクトで使用しているフレームワークとツールを確認します（package.json を確認してください）
• knip の設定ファイル（knip.json、knip.jsonc、または package.json の knip キー）があるか確認します
• 設定ファイルがある場合は、改善できる点がないか確認します（下記の「設定のベストプラクティス」を参照）

ステップ 2：まず knip を実行し、設定に関するヒントを読む

npx knip

何よりも先に、設定に関するヒントを確認してください。これらは出力の先頭に表示され、誤検出を減らすための設定変更を提案します。

ステップ 3：knip.json を調整してヒントに対処する

報告された問題に対処する前に、設定に関するヒントを解消してください。一般的な調整は次のとおりです。

• 検出されたフレームワークに応じてプラグインを有効化／無効化する
• 標準的でないエントリーポイントのパターンを追加する
• モノレポのワークスペース設定を構成する

ステップ 4：ステップ 2～3 を繰り返す

設定を変更するたびに knip を再実行します。設定に関するヒントが解消され、誤検出が最小限になるまで繰り返してください。

ステップ 5：実際の問題に対処する

設定が確定したら、報告された問題に取り組みます。次の順に優先してください。

1. 未使用ファイル — 最初に対処します（「受信箱ゼロ」の方法でノイズを最も減らせます）
2. 未使用の依存関係 — package.json から削除します
3. 未使用の devDependencies — package.json から削除します
4. 未使用のエクスポート — 削除するか、内部用としてマークします
5. 未使用の型 — 削除するか、ignoreExportsUsedInFile を設定します（下記を参照）

ステップ 6：再実行して繰り返す

修正を行うたびに knip を再実行します。未使用ファイルを削除すると、新たに未使用となったエクスポートや依存関係が見つかることがよくあります。

設定のベストプラクティス

knip の設定を確認または作成する際は、次のルールに従ってください。

• ignore パターンは絶対に使用しないでください — ignore は実際の問題を隠すため、ほとんどの場合は使用すべきではありません。必ず具体的な解決策を優先してください。その他の ignore* オプション（ignoreDependencies、ignoreExportsUsedInFile など）は、特定の問題の種類を対象とするため問題ありません。
• 未使用のエクスポートされた型が多い場合 — ignoreExportsUsedInFile: { interface: true, type: true } を追加します。これにより、同じファイル内でのみ使用される型という一般的なケースに対処できます。より広範な ignore オプションよりも、こちらを優先してください。
• 冗長なパターンを削除する — Knip はすでに .gitignore を尊重するため、node_modules、dist、build、.git を無視する設定は冗長です。
• デフォルト設定で網羅されるエントリーパターンを削除する — 自動検出されたプラグインは、標準的なエントリーポイントをすでに追加します。重複して追加しないでください。
• 設定ファイルが未使用として表示される場合（例：vite.config.ts）— ファイルを無視するのではなく、対応するプラグインを明示的に有効化または無効化します。
• Node.js の組み込みモジュールと一致する依存関係の場合（例：buffer、process）— ignoreDependencies に追加します。
• パスエイリアスからのインポートを解決できない場合 — knip の設定に paths を追加します（tsconfig.json のセマンティクスを使用します）。

本番モード

本番コードのみを対象にするには、--production を使用します。

npx knip --production

これにより、テストファイル、設定ファイル、その他の本番以外のエントリーポイントが除外されます。テストファイルを除外するために project または ignore パターンを使用しないでください。代わりに --production を使用してください。

クリーンアップの確信度

自動削除（高い確度）：

• 明らかに内部向けの未使用エクスポート（パブリック API の一部ではないもの）
• 未使用の型エクスポート
• 未使用の依存関係（package.json から削除します）
• 明らかに孤立している未使用ファイル（エントリーポイントや設定ファイルではないもの）

先に確認（要確認）：

• エントリーポイントまたは動的にインポートされている可能性のあるファイル
• パブリック API の一部である可能性のあるエクスポート（index.ts、lib のエクスポート）
• CLI やピア依存関係を通じて使用されている可能性のある依存関係
• src/index、lib/ などのパスにあるものや、名前に「public」または「api」が含まれるファイル

これらを削除する前に、AskUserQuestion ツールを使用して確認してください。

自動修正

設定が確定し、結果に確信が持てたら、次を実行します。

# Auto-fix safe changes (removes unused exports and dependencies)
npx knip --fix

# Auto-fix including file deletion
npx knip --fix --allow-remove-files

設定を先に行うワークフローが完了するまで、--fix は使用しないでください。

エラー処理

knip がコード 2（「error loading file」などの予期しないエラー）で終了した場合：

• 設定ファイルがあるか確認します。ない場合は、プロジェクトのルートに knip.json を作成します
• knip.dev で既知の問題を確認します
• 構文やオプションのエラーがないか、設定リファレンスを確認します
• 修正後、再度 knip を実行します

よく使うコマンド

# Basic run
npx knip

# Production only (excludes test/config entry points)
npx knip --production

# Auto-fix what's safe
npx knip --fix

# Auto-fix including file deletion
npx knip --fix --allow-remove-files

# JSON output for parsing
npx knip --reporter json

注意事項

• モノレポのセットアップに注意してください。--workspace フラグが必要な場合があります
• 一部のフレームワークでは、設定でプラグインを有効にする必要があります
• Knip はファイル内の未使用インポートや未使用変数を検出しません。その場合は ESLint または Biome を使用してください