依存関係の迷宮を制する：peerDependencies との「正しい距離感」と「強制制御」の技術
フロントエンド開発の現場で、`npm install` を実行した瞬間に吐き出されるあの真っ赤なエラーログ。`peerDependencies` の競合に頭を抱え、`–legacy-peer-deps` という魔法の呪文で現実から目を背けてはいないだろうか。
多くのエンジニアが「なんとなく」で済ませているこの依存関係の制約は、実は「ライブラリ間のインターフェースを型安全かつバージョン的に保証する」という、極めて重要な契約である。今回は、npm/pnpmの内部構造を理解し、この「地獄」を戦略的に飼いならすためのアーキテクチャ設計を解説する。
—
1. なぜ「peerDependencies 地獄」は起きるのか？
`peerDependencies` は、ライブラリが「直接依存してはいないが、ホストアプリケーション（実行環境）に特定のパッケージが存在することを要求する」ための仕組みだ。
しかし、依存関係が深くなると「AがReact 17を要求し、BがReact 18を要求する」といった状況が発生する。npmのフラットな構造は、これを解決できずに停止する。ここで重要なのは、「依存の競合は、単なるエラーではなく、互換性の欠如を知らせるシグナルである」という事実だ。
「強制解決」のその先へ：overrides という名の外科手術
もし、競合しているライブラリが「実際には最新のバージョンでも動作する」ことが分かっているなら、私たちは `package.json` の `overrides`（npm）または `pnpm.overrides`（pnpm）を使用して、依存関係グラフを強制的に書き換えるべきだ。
実用的な設定例：npmの場合
{
“overrides”: {
// 依存先が古い特定のライブラリを使っていても、強制的に最新版を注入する
“styled-components”: “^6.0.0”,
“react-query”: {
// 特定のパッケージ配下の依存のみを差し替える外科手術的アプローチ
“react”: “$react”
}
}
}
注: `$react` は自身の `dependencies` に定義された React バージョンを参照する特殊なシンタックスである。
—
2. pnpm を選ぶべき「真の理由」：厳格な依存解決
npmの「フラットな node_modules」は、存在しないはずのパッケージにアクセスできてしまう「幽霊依存（Phantom Dependencies）」を生み出す。これに対し、pnpm はシンボリックリンクを駆使し、明示的に宣言された依存しか解決できない「隔離された環境」を構築する。
チーム開発を加速させる `pnpm-workspace.yaml` の極意
大規模なモノレポで依存関係を制御する場合、pnpmの「ワークスペース」機能は必須だ。
pnpm-workspace.yaml
packages:
- ‘packages/’
- ‘apps/’
依存のルールを強制する
catalog:
# 全パッケージで共通のバージョンを強制し、バージョン乖離による地獄を未然に防ぐ
react: ^18.2.0
typescript: ^5.0.0
これにより、CI/CD上で「あるパッケージだけ古いバージョンを使っている」という事故をビルドタイムで検知できる。
—
3. ライブラリ開発者が守るべき「聖域のルール」
自分がライブラリを公開する立場なら、以下の原則を叩き込んでほしい。
1. peerDependencies は広く、dependencies は最小限に:
ライブラリの `dependencies` に React を入れると、ユーザーの環境で React が二重にインストールされるリスクがある。必ず `peerDependencies` で指定し、`peerDependenciesMeta` で「任意」であることを示唆すること。
2. 型定義の同期:
`@types/xxx` は必ず `devDependencies` に入れる。そしてユーザーにはピア依存としてインストールを促す。
—
4. 生産性を極限まで引き上げる神ツールと習慣
導入すべき神プラグイン・設定
- [syncpack](https://github.com/jamiemason/syncpack):
モノレポ内の `package.json` を横断的にチェックし、バージョン不整合を修正する。これを `husky` でコミットフックに仕込むだけで、依存管理のストレスは8割減る。
- [depcheck](https://github.com/depcheck/depcheck):
使われていない依存を検知する。ビルド成果物を肥大化させる「ゾンビ依存」を定期的に駆逐せよ。
現場で震えるほど役立つコマンド
pnpm: 依存関係の視覚化（競合箇所を一発で特定） npm: 依存のツリーを再帰的に確認（なぜこのバージョンが入っているのかを追跡） — `peerDependencies` のエラーは、あなたが「どのような依存グラフでアプリケーションを構築したいか」を定義するための対話である。 `overrides` で無理やり解決するのも一手だが、それはあくまで緊急避難だ。真の解決策は、依存関係の意図を明確にし、`pnpm` のような厳格なパッケージマネージャを採用し、`syncpack` のような自動化ツールで「設定の整合性」を担保するアーキテクチャにある。 ツールに振り回されるのではなく、ツールを制し、依存関係の迷宮を設計図通りに塗り替える。それこそが、現場をリードするテックエンジニアのあり方だ。 さあ、今すぐ `package.json` を開き、その「場当たり的な解決」を「論理的な設計」へと書き換えよう。
pnpm why
npm list 結論：依存関係は「管理」ではなく「設計」する