npm-deps-cleanup

npm 依存関係の整理

JavaScript の依存関係を削減します。具体的な理由がない限り、既存のパッケージマネージャー、ロックファイル、ワークスペース構成、依存関係の範囲指定のスタイルを維持してください。

ワークフロー

1. ベースラインを確認します。
2. 未使用の直接依存関係を削除します。
3. モノレポ内の直接依存関係のバージョンを重複排除します。
4. ロックファイルの推移的依存関係のクロージャに基づいて、直接依存関係を順位付けします。
5. クロージャのデータを使って、リスクの低いマイナー／パッチアップグレードを見つけます。
6. クロージャのデータを使って、インライン化に値する単純な依存関係を見つけます。
7. e18e の推奨事項を確認し、置き換えや削除を検討します。
8. 再インストールして検証し、測定した効果を報告します。

パッケージマネージャーの検出

リポジトリで既に使用されているパッケージマネージャーを使います。ロックファイルよりも、明示的なパッケージメタデータを優先してください。

1. ルートの package.json にある packageManager。
2. ルートの package.json にある devEngines.packageManager.name。
3. ロックファイルからの推定。

devEngines.packageManager が存在する場合、npm、pnpm、Yarn、Bun の判定にはその name を使います。version と onFail のフィールドはポリシーを示すものとして扱い、パッケージマネージャーを変更する許可とは見なしません。

パッケージメタデータからパッケージマネージャーを特定できない場合に限り、ロックファイルから推定します。

シグナル	パッケージマネージャー
package-lock.json または npm-shrinkwrap.json	npm
pnpm-lock.yaml	pnpm
yarn.lock	Yarn
bun.lock または bun.lockb	Bun

対応するコマンド群を使います。

操作	npm	pnpm	Yarn	Bun
インストール／ロックファイルの更新	npm install	pnpm install	yarn install	bun install
直接依存関係の削除	npm uninstall <pkg>	pnpm remove <pkg>	yarn remove <pkg>	bun remove <pkg>
直接依存関係の追加／更新	npm install <pkg>@<version>	pnpm add <pkg>@<version>	yarn add <pkg>@<version>	bun add <pkg>@<version>
依存関係の説明	npm explain <pkg>	pnpm why <pkg>	yarn why <pkg>	bun pm why <pkg> if available
ロックファイルの重複排除	npm dedupe	pnpm dedupe	yarn dedupe if available	再インストールして確認
単発ツール	npx <tool>	pnpm dlx <tool>	yarn dlx <tool> if available	bunx <tool>

安全ルール

• ロックファイルの差分をレビューしやすく保つため、少量ずつ作業します。
• 未使用依存関係を調べるツールを鵜呑みにしないでください。インポート、設定ファイル、スクリプト、生成コードのフック、フレームワークの規約、プラグイン名、CLI、動的インポートを確認します。
• package.json とロックファイルの依存関係の整合性を検証するために、スクリプトの作成や解析を行ってもかまいません。
• peerDependencies、optionalDependencies、パッケージの bin の使用箇所、テスト用フィクスチャ、公開パッケージのマニフェストは、リスクが高いものとして扱います。
• セキュリティ、解析、暗号化、Unicode、URL 処理、日付／時刻、i18n、プラットフォーム互換性のために使われている依存関係は、置き換えが同等であると証明できない限り、削除したりインライン化したりしないでください。
• クリーンアップの一環として、パッケージマネージャーを変更したり、ロックファイルを削除したり、ワークスペース構成を書き換えたりしないでください。
• パッケージマネージャーの重複解消コマンドは、動作を変える可能性があるものとして扱います。許容範囲内で選択される推移的依存関係のバージョンが変わることがあるため、ロックファイルの差分を調べ、結果を採用する前に対象を絞って検証します。
• 変更前と変更後を計測します。直接依存関係の数、ロックファイルの行数またはエントリー数、パッケージ数、可能な場合は node_modules の推定サイズを記録します。

ステップ 1：ベースライン

以下を収集します。

• すべての package.json ファイルとワークスペースの境界。
• 現在のパッケージマネージャーとロックファイル。
• マニフェストのセクションごとの直接依存関係名：dependencies、devDependencies、peerDependencies、optionalDependencies。
• スクリプト、CI、リポジトリのドキュメントにある既存の検証コマンド。

編集前に、ベースライン指標を記録します。

git status --short
wc -l <lockfile>

node_modules がインストールされている場合は、プラットフォームに適したファイルシステムツールを使って、インストール済みの容量も推定します。容量のクリーンアップを node_modules の有無に依存させないでください。主な指標はロックファイルの削減です。

ステップ 2：未使用の直接依存関係を削除する

静的解析ツールは出発点として使い、証明として扱わないでください。候補としては、knip、depcheck、またはすでに設定されているリポジトリ固有のツールが適しています。インストールされていない場合は、検出したパッケージマネージャーの一時実行機能を使って実行します。

候補ごとに、次の作業を行います。

1. コード、設定、パッケージスクリプト、ビルドツール、テスト、ドキュメントで、パッケージ名と既知のインポートパスを検索します。
2. 公開パッケージのマニフェスト、ピア依存関係の契約、プラグインローダー、CLI コマンド、動的な require／import でその依存関係が必要か確認します。
3. 実際の使用箇所が残っていない場合に限り、削除します。
4. 検出したパッケージマネージャーで再インストールし、対象を絞って検証します。

スクリプトまたは設定でのみ使用されている場合は、削除するのではなく、dependencies と devDependencies の間で移動することを検討してください。

ステップ 3：モノレポ内の直接依存関係のバージョンを統一する

モノレポでは、同じ直接依存関係が複数のパッケージマニフェストで異なるバージョン／範囲を指定していないか確認します。まず既存の方針を適用します。たとえば、完全固定、キャレット範囲、カタログ／プロトコルの使用、ワークスペースプロトコル、中央制約などです。

推奨される方法：

• syncpack list-mismatches または同等のパッケージマネージャーに依存しないツールを使って検出します。
• パッケージ間で互換性のある同一バージョンを共有できる場合は、直接依存関係の範囲を統一します。
• オーバーライド／リゾリューションを追加する前に、マニフェストレベルの一貫性を優先します。
• オーバーライド／リゾリューションは、推移的依存関係の収束またはセキュリティ修正に限って使い、その理由を記録します。

重複解消後は、再インストールし、マニフェストとロックファイルの両方の差分を確認します。

続いて、パッケージマネージャーにネイティブのロックファイル重複解消コマンドがあれば、実行を検討します。npm dedupe、pnpm dedupe、または利用可能な場合は yarn dedupe を使います。Bun には直接対応するコマンドがありません。bun install を実行し、ロックファイルが収束するか確認します。これらのコマンドは、マニフェストを編集していなくても推移的依存関係の解決を変え、問題を引き起こす可能性があるため、慎重に適用してください。

ステップ 4：推移的なロックファイル依存関係の範囲を評価する

重要な直接依存関係ごとに、その依存関係から到達できる推移的なロックファイル項目の集合である依存範囲を見積もります。

次の両方を報告します。

• 依存範囲の合計：その依存関係から到達可能なすべてのパッケージ。
• 依存範囲の独占分：その依存関係を削除した場合に消え、ほかの直接依存関係によって維持されないパッケージ。

推測よりも、再現性のある測定を優先します。パッケージマネージャーに依存しない代替手順は次のとおりです。

1. ベースラインとなるロックファイルの指標を保存します。
2. 対象のマニフェストから直接依存関係を一時的に削除します。
3. 検出したパッケージマネージャーの install を実行します。
4. ロックファイルの行数／項目数の減少と、パッケージ数の減少を測定します。
5. 次の依存関係を測定する前に、一時的な削除を元に戻します。

大きな推移的パッケージが存在する理由を理解するには、npm explain、pnpm why、yarn why、または利用可能なパッケージマネージャーの依存関係グラフコマンドを使います。依存関係は、単純なサイズではなく、影響度とリスクに基づいて順位付けします。

ステップ 5：リスクが低く影響の大きいアップグレードを見つける

依存範囲の順位を参考に、新しいマイナー／パッチバージョンによって推移的な依存関係が減る直接依存関係を対象にします。

候補ごとに、次の手順を実行します。

1. パッケージマネージャーの outdated/info コマンドを使って、利用可能なメジャー以外のバージョンを確認します。
2. 依存関係ツリーの変更と互換性に関する注意事項について、変更履歴／リリースノートを確認します。
3. 一度に 1 つの依存関係、または密接に関連する依存関係群をアップグレードします。
4. 再インストールし、前後の依存範囲の指標を比較します。
5. 対象を絞ったテストと、関連するビルド／型チェックコマンドを実行します。

ユーザーが移行リスクを明示的に受け入れない限り、メジャーアップグレードは避けてください。

ステップ 6：簡単な使用箇所をインライン化する

依存範囲の順位を参考に、コードベース内での使い方は小さく明白なのに、推移的なコストが大きい直接依存関係を見つけます。

次のすべてに該当する場合に限り、インライン化します。

• 使用箇所がごく小さく、すべてを簡単に把握できます。
• 同等のコードを使うほうが、依存関係を維持するより短いか明確です。
• 動作がテストでカバーされているか、小規模な特性テストでカバーできます。
• その依存関係が、クロスプラットフォーム対応、セキュリティ、解析、Unicode、ロケール、または仕様準拠に関するエッジケースを解決しているものではありません。

必要な動作が単純な場合は、新しい代替依存関係を追加するより、ネイティブ API を優先します。

ステップ 7：e18e のガイダンスを適用する

削除や置き換えの候補を追加で探すため、e18e を参照します。

<runner> @e18e/cli analyze
<runner> @e18e/cli migrate --dry-run

<runner> は、検出した単発実行用ツール（npx、pnpm dlx、yarn dlx、または bunx）に置き換えてください。

また、既知の代替手段については、e18e のモジュール置き換えリスト https://e18e.dev/docs/replacements/ も確認します。推奨事項は必須事項ではなく候補として扱い、バンドル／ランタイムの動作を確認してテストを実行してください。

報告

測定した影響を含めて結果を要約します。

• 削除または移動した直接依存関係。
• 重複を解消した直接依存関係のバージョン。
• ロックファイルの行数／項目数の削減。
• 入手可能な場合は、推定パッケージ数または node_modules の削減。
• 対応を見送った影響の大きい候補と、その理由。
• 実行した検証コマンドと結果。

削除の判断がランタイムでのカバレッジではなく静的解析に依存する場合は、リスクを明示してください。