npm/yarnの「幽霊依存」を根絶せよ：pnpm `–no-hoist` で実現する真の依存関係分離戦略
フロントエンド開発の現場において、`node_modules` は時に「ブラックボックス」と化します。npmやyarnが採用しているフラットな構造は、かつての依存関係地獄（ネスト問題）を解決しましたが、代償として「本来インストールしていないはずのパッケージが、なぜかrequire/importできてしまう」という、いわゆる「幽霊依存（Phantom Dependencies）」という深刻な副作用を招きました。
本稿では、pnpmの強力な機能である `hoist-pattern` の制御、特に `–no-hoist` を活用した「依存の隔離」による、堅牢で予測可能なアーキテクチャの構築術を伝授します。
—
1. なぜ「Hoisting（引き上げ）」が諸悪の根源なのか
npmやyarnは、依存関係をフラットに解決するために、サブ依存関係をルートの `node_modules` に引き上げます。これにより、パス解決のパフォーマンスは向上しますが、以下の致命的な問題が発生します。
- 暗黙の依存: `package.json` に記述していないパッケージが、依存先の依存先としてインストールされ、コード内で `import` できてしまう。
- バージョンの不整合: 複数のパッケージが異なるバージョンのライブラリを要求した際、本来期待していないバージョンがフラット構造の隙間に紛れ込む。
- デプロイ事故: ローカル環境では動くのに、CI環境や別環境でビルドすると「Module not found」で落ちる。これは開発環境と実行環境の「再現性」が担保されていない証拠です。
pnpmは、シンボリックリンクを活用したコンテンツアドレス指定ストレージにより、この問題を本質的に解決します。
—
2. 実践：`public-hoist-pattern` と `–no-hoist` の極意
pnpmにおいて、依存関係を完全に分離・制御するための `.npmrc` 設定のベストプラクティスを提示します。
`.npmrc` による厳格な管理
プロジェクトのルートに配置する `.npmrc` で、意図しない引き上げを禁止します。
すべてのパッケージの引き上げを無効化（これが最強の隔離）
これにより、package.json に明記されたもの以外は絶対に見えなくなる
public-hoist-pattern[]=
ただし、特定のビルドツール等、どうしても引き上げが必要な場合のみ例外を許可する
例：ESLintやPrettierのプラグイン系は引き上げないと動作しないことが多い
public-hoist-pattern[]=eslint
public-hoist-pattern[]=prettier
厳格なモードを有効化
依存関係の欠落をビルド時に確実に検知する
strict-peer-dependencies=true
なぜこの設定が「開発スピード」を上げるのか
「動くはずのコードが動かない」というデバッグに費やす時間は、エンジニアにとって最大の損失です。依存関係を厳格にすることで、「コードが動く理由」が常に明文化（package.jsonによる証明）されるため、CIでのビルド失敗が激減し、リファクタリング時の心理的安全性も劇的に向上します。
—
3. チーム開発を加速させる「神」設定と運用ルール
テックリードとして、以下の運用をチームに強制・推奨してください。
① `pnpm-workspace.yaml` によるモノレポ構造の最適化
モノレポ環境であれば、各パッケージ間での依存の漏れを防ぐために以下の設定を入れます。
pnpm-workspace.yaml
packages:
- ‘packages/’
- ‘apps/’
共有パッケージの依存関係を隔離し、個別のアプリが勝手に
親の依存関係を吸い上げないようにする
catalog:
‘@acme/ui’: workspace:
② 絶対入れるべき神プラグイン：`pnpm-deduplicate`
依存関係を隔離しても、モノレポ内では重複したバージョンが混入しがちです。`pnpm-deduplicate` を定期的に実行し、`pnpm-lock.yaml` を最適化しましょう。
ロックファイルをスキャンし、不要な重複バージョンを排除する
npx pnpm-deduplicate
③ VS Code 開発効率化ショートカット
pnpmコマンドをターミナルで打つ時間を削るため、`tasks.json` にコマンドを登録し、`Cmd + Shift + B` でビルドを走らせるのが現代の定石です。
{
“version”: “2.0.0”,
“tasks”: [
{
“label”: “pnpm install”,
“type”: “shell”,
“command”: “pnpm install –frozen-lockfile”,
“group”: “none”
}
]
}
※ `–frozen-lockfile` をつけることで、ローカルの `pnpm-lock.yaml` を書き換えることなく、CI環境と同一の依存関係を強制できます。
—
4. 現場のテックリードからのアドバイス
「隔離」を徹底することは、最初は苦痛を伴います。今まで動いていたコードが `Module not found` を吐くようになるからです。しかし、それは「今まで泥酔状態で運転していた車に、ようやくブレーキを付けた」のと同じことです。
1. 段階的移行: 最初から `no-hoist` を全適用せず、特定のパッケージから除外設定を行い、徐々に範囲を広げてください。
2. 型定義の確認: TypeScript環境では、`tsconfig.json` の `paths` 設定と `pnpm` のリンク構造が競合しないよう注意してください。
3. CIでの検証: 必ず `pnpm install –frozen-lockfile` をCIの最初の一歩にしてください。これにより、依存関係の不法侵入を即座に検知できます。
結論
pnpmの `–no-hoist` 戦略は、単なるツールの設定変更ではありません。それは、「依存関係の透明性」というアーキテクチャの規律をコードに刻み込む行為です。この規律を守るチームは、大規模化しても崩壊せず、常にクリーンなビルド環境を維持し続けることができるのです。
さあ、今すぐ `.npmrc` を開き、その「不法侵入」を断ち切る準備を始めましょう。