node_modulesという「負の遺産」を葬る：Yarn PnPがもたらす開発体験の特異点
フロントエンドエンジニアが抱える永遠の業、それは `node_modules` のカオスです。数百万の小さなファイルを抱え、I/O負荷でSSDを悲鳴を上げさせ、シンボリックリンクの海に溺れる。この構造こそが、CIのビルド時間を増大させ、キャッシュの汚染を招く真因です。
Yarn Berry (v2+) の Plug’n’Play (PnP) は、単なるパッケージ管理の改良ではありません。Node.jsのモジュール解決アルゴリズムそのものを「書き換える」という、極めて挑戦的なアーキテクチャです。本稿では、node_modulesの支配から脱却し、究極のビルドパイプラインを構築するための深層技術を解説します。
—
1. node_modulesの終焉：PnPのアーキテクチャ
なぜ `node_modules` は遅いのか？ それは「ディスク上の階層構造を探索し、ファイルシステムを再帰的にトラバースする」という古のアルゴリズムに依存しているからです。
PnPは、これに代わり `.pnp.cjs` という単一のルックアップテーブルを生成します。
- 物理的な分離: 全パッケージを単一のグローバルキャッシュ（`.yarn/cache`）にZIP形式で保持。
- インメモリ解決: モジュールの位置はメモリ上のマップで解決されるため、I/Oアクセスはゼロ。
- 決定論的解決: `package.json` の依存関係が物理的にどこにあるかを完全に制御できるため、「幽霊依存（hoistingの副作用で存在しないはずのパッケージが見えてしまう現象）」が物理的に発生し得ません。
—
2. 実戦的移行とIDEインテグレーション
PnPへの移行は単なる設定変更ではなく、プロジェクトの「衛生状態」を正すプロセスです。
移行の要諦
プロジェクトルートで以下を実行します。
Yarn Berryの有効化（Zero-installs戦略のためリポジトリに含める）
yarn set version berry
PnPモードの強制適用
yarn config set nodeLinker pnp
IDE連携の罠を突破する
VSCodeでPnPを使う際、Language ServerがZIPの中身を見失うのは致命的です。ここで ZipFS 拡張機能の登場です。
// .vscode/settings.json
{
// TypeScriptに対して、PnPの解決ロジックを注入するSDKの使用を強制
“typescript.tsdk”: “.yarn/sdks/typescript/lib”,
“typescript.enablePromptUseWorkspaceTsdk”: true
}
※ `yarn dlx @yarnpkg/sdks vscode` を実行することで、VSCodeに必要なSDKと設定が自動生成されます。これをしないと、IDEは「モジュールが見つからない」と赤い波線で埋め尽くされます。
—
3. CI/CDパイプラインの最適化：Zero-installsの境地
上級エンジニアが目指すべきは、CIにおける「インストール時間の消滅」です。Yarn Berryの真骨頂である Zero-installs を採用してください。
`.yarn/cache` をリポジトリにコミットすることで、CIサーバーは `yarn install` を実行する必要すらなくなります。
GitHub Actionsの例
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build
# インストール不要。キャッシュから直接解決される
run: yarn build
なぜこれが最強なのか？
CIの失敗の多くは `npm install` 中のネットワークエラーや、Registryの不安定さに起因します。Zero-installsは、依存関係がコードベースの一部であるため、ネットワーク依存性を完全に排除し、ビルドの再現性を100%保証します。
—
4. Docker環境での完全自動構成：低レイヤからのハック
DockerでPnPを動かす場合、キャッシュの効率的なマウントが鍵です。
マルチステージビルドで容量を最適化
FROM node:20-slim AS base
WORKDIR /app
Yarnの設定ファイルを先にコピー
COPY .yarnrc.yml .yarn/
COPY .yarn .yarn/
COPY package.json yarn.lock .pnp.cjs ./
PnP対応のインストール
RUN yarn install –immutable
ビルド実行
COPY . .
RUN yarn build
ここで重要なのは、`–immutable` フラグです。これにより、ロックファイルと整合性が取れない場合に即座にエラーを吐き、CIの汚染を検知します。
—
5. トラブルシューティング：PnPを掌握する
PnP導入で最も多い躓きは、ネイティブアドオン（C++ビルドが必要なライブラリ） です。これらは通常の `require()` では読み込めない場合があります。
解決策として、`pnpify` を活用します。
既存ツールがPnP非対応の場合、ラップして実行
yarn pnpify node script.js
また、依存関係の矛盾を突き止めるには以下のコマンドが必須です。
どのパッケージが何に依存し、どこで解決されているかを表示 — `node_modules` は、かつてないほど巨大化するWebフロントエンドにとって、もはやボトルネック以外の何物でもありません。PnPへの移行は、単なるツールの変更ではなく、「開発環境のレイテンシを物理的にゼロに近づける」 というエンジニアリングの姿勢そのものです。 もしあなたが、CIの実行時間に毎日数分を浪費しているなら、今日がその脱却の日です。PnPは、複雑性を隠蔽するのではなく、複雑性を「解決可能なデータ」へと変貌させます。これこそが、モダンなDevOpsが目指すべき地平なのです。
yarn why アーキテクトの最終提言