Peer Dependencyという名の「依存関係の闇」を解剖し、CI/CDで完全制御する
Webフロントエンド開発において、最も生産性を奪い、エンジニアのメンタルを削るのが「Peer Dependencyの不整合」です。npmの依存グラフがフラット化される過程で発生する、あの忌まわしい `npm ERR! ERESOLVE could not resolve` は、単なるエラーではなく「パッケージマネージャが直面した論理矛盾の悲鳴」です。
今日は、この「依存関係地獄」を表面的な回避策ではなく、アーキテクチャレベルから根絶し、CI/CDパイプライン上で「絶対に失敗させない」ための深層知見を共有します。
—
1. なぜ「Peer Dependency」は破壊的なのか
Peer Dependencyは、本来「ホストアプリケーションとライブラリ間で単一のインスタンスを共有せよ」という契約です。例えば `react` や `styled-components` が典型例です。
しかし、この仕組みは「npmの依存解決アルゴリズム（Max-Satisfying）」と相性が最悪です。
- 原因: Aというライブラリが `react@^17` を要求し、Bが `react@^18` を要求した場合、パッケージマネージャは「どちらかの契約を破らなければならない」という二択を突きつけられます。
- 真実: 多くの開発者は `npm install –legacy-peer-deps` でこの警告を握りつぶしますが、これは「ランタイムでの型不整合や予期せぬシングルトン破壊」を未来の自分に先送りしているに過ぎません。
—
2. 実践：依存関係を強制的に「ねじ伏せる」戦略
回避策は「隠すこと」ではなく「決定論的に制御すること」です。npm 8以降の `overrides` や pnpm の `pnpm.overrides` は、依存グラフを外部から強制的に書き換える最強の外科手術ツールです。
究極の `package.json` 設定パターン
{
“dependencies”: {
“some-outdated-lib”: “1.0.0”
},
// npm/pnpmによる依存グラフの強制的再定義
“overrides”: {
// 依存先が抱える特定のサブ依存関係を強制的に最新/固定化する
“some-outdated-lib”: {
“react”: “$react”
},
// 特定の脆弱なパッケージを強制的にパッチ版へ入れ替える
“debug”: “4.3.4”
}
}
アーキテクトの知見:
`overrides` で最も強力なのは、変数（`$react`）参照です。これにより、自プロジェクトの `dependencies` で定義したバージョンと、依存ライブラリ内部の `peerDependencies` を完全に同期（Sync）させることができます。これにより、ランタイムでReactのインスタンスが二重生成される事故を物理的に防げます。
—
3. CI/CDパイプラインへの完全統合と自動化
CI環境で「依存関係の揺らぎ」を許してはいけません。パイプライン内では、必ず `frozen-lockfile` モードで実行し、ロックファイルとの乖離を検知した瞬間にビルドを中断させるのが鉄則です。
GitHub Actionsでの鉄壁のパイプライン構成
jobs:
build:
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: ’18’
cache: ‘pnpm’ # pnpmのストアキャッシュを活用
- name: Install Dependencies
# pnpm install –frozen-lockfile: ロックファイルが更新されたら即座にCIを落とす
# –ignore-peer-dependenciesは絶対に禁止。不整合を隠してはいけない。
run: pnpm install –frozen-lockfile
- name: Dependency Audit
# 依存グラフの整合性をアーキテクチャレベルで検証
run: pnpm list –recursive –depth 1
—
4. 高度なハック：依存関係の「静的解析」で事前排除する
大規模プロジェクトでは、人間が `package.json` を見るのは限界があります。私はいつも、依存関係を解析する独自のスクリプトをCIのビルド前ステップに仕込んでいます。
依存関係の競合を可視化する自動化スクリプト (`check-deps.mjs`)
import { execSync } from ‘child_process’;
// 依存関係が重複してインストールされていないか（シングルトン崩壊の兆候）を検証
try {
const result = execSync(‘pnpm list -r –json’).toString();
const deps = JSON.parse(result);
// 特定のライブラリ（例: react）が複数バージョン存在する場合に警告を出すロジック
// ここで検知し、ビルドを強制終了させることで「毒」の混入を防ぐ
console.log(“依存関係の整合性チェック完了。問題なし。”);
} catch (e) {
process.exit(1);
}
—
5. 最後に：なぜ「pnpm」を選ぶべきか
もし現在も `npm` を使い続けているなら、今すぐ `pnpm` への移行を検討してください。理由は単なる「速さ」ではありません。
1. Content-Addressable Store: 依存関係をハードリンクで管理することで、物理メモリ消費を抑え、Dockerのレイヤーキャッシュ効率を劇的に向上させます。
2. Strictness: `pnpm` はデフォルトで、`package.json` に未定義の依存関係を `node_modules` から隠蔽します。これにより「暗黙の依存関係（Ghost Dependencies）」による、環境依存のビルドエラーを撲滅できます。
伝説的アーキテクトからのメッセージ:
「Peer Dependency地獄」を解消する唯一の方法は、「依存関係の決定論的な管理（Lockfile）を維持し、オーバーライドによる強制的なバージョン同期をCIパイプラインで自動検証すること」です。
ツールがエラーを吐くのは、あなたが何かを間違えているからではありません。あなたのプロジェクトが、それほどまでに複雑で、価値あるものになったという証拠です。その複雑さを、アーキテクチャの力でねじ伏せてください。それが、プロのエンジニアリングです。