モノレポの悪夢を終わらせる：pnpm Workspaceがもたらす「真の依存関係」の最適化
こんにちは。日々、コードの海を渡る皆さんの開発体験（DX）を最大化することに情熱を燃やしているエンジニアです。
フロントエンド開発が複雑化する昨今、複数のライブラリやアプリケーションを一つのリポジトリで管理する「モノレポ」は避けて通れない道です。しかし、多くの現場で「npm linkの沼」にハマり、疲弊しているエンジニアをよく見かけます。
今日は、なぜ npm や yarn の従来の手法がモノレポで限界を迎えるのか、そして pnpm Workspace を使うことが、なぜあなたの開発フローを「次元が違うレベル」へと押し上げるのか。その深層を解説します。
—
1. なぜ「npm link」は地獄の入り口なのか？
従来の `npm link` は、文字通り「シンボリックリンク」を強制的に作成し、パッケージを配置します。しかし、これには致命的な欠陥があります。
- 依存関係の不整合: リンク先のノードモジュールが、リンク元のプロジェクトと異なるバージョンを参照してしまう「幽霊依存（Phantom Dependencies）」が発生しやすい。
- 再現性の欠如: `npm link` した環境は開発者のローカルPC固有の状態であり、CI/CD環境で全く同じ状態を再現するのが困難。
- 巨大化するnode_modules: プロジェクトごとに依存パッケージが重複してコピーされ、ディスク容量とビルド時間を浪費する。
pnpm は、「コンテンツアドレス可能ストレージ（CAS）」という仕組みを採用しています。すべてのパッケージをPC内のグローバルな単一ストアに保存し、そこからハードリンクを生成することで、これらの問題を根本から解決します。
—
2. pnpm Workspaceによる「依存の可視化」
pnpm Workspaceを使うと、モノレポ内の各パッケージを「公開せずに」ローカルで相互参照できます。まずは、最も効率的な構成をセットアップしましょう。
プロジェクトの雛形作成
まず、ルートディレクトリに `pnpm-workspace.yaml` を配置します。これがモノレポの「脳」となります。
pnpm-workspace.yaml
このプロジェクトに含まれるパッケージの場所を定義します
packages:
- ‘packages/’ # 共有ライブラリ群
- ‘apps/’ # アプリケーション群
次に、ルートの `package.json` でワークスペースの機能を有効にします。
{
“name”: “my-monorepo”,
“private”: true, // ルート自体はパッケージとして公開しない
“scripts”: {
“dev”: “pnpm -r –filter ./apps/ dev”
// -r: 再帰的（recursive）実行
// –filter: 特定のディレクトリ配下のみを対象にする強力な絞り込み
}
}
—
3. HelloWorldを超えて：ローカルパッケージの連携
例えば、`packages/ui-kit`（共通UI）を `apps/web-app` で使いたい場合、ただこう打つだけです。
apps/web-app ディレクトリに移動し、ui-kit をインストール
cd apps/web-app
pnpm add @my-repo/ui-kit –workspace
この `–workspace` オプションが重要です。これにより、pnpm は外部のレジストリを探しに行くのではなく、「今このワークスペース内にあるバージョン」を自動的にリンクしてくれます。
なぜこれが「震えるほど役立つ」のか？
1. リアルタイムな変更検知: `packages/ui-kit` のコードを修正した瞬間、`apps/web-app` 側でビルドやホットリロードが即座に走ります。
2. ビルド順序の自動解決: `pnpm build` を叩くと、依存関係のグラフを解析し、`ui-kit` がビルドされた後に `web-app` がビルドされるように自動制御されます。依存の逆転やタイミングエラーとはもうおさらばです。
—
4. 現場で生きる「フィルタリング」の真髄
CI/CDにおいて最もコストがかかるのは「全パッケージのビルド」です。pnpm のフィルタリング機能を活用すれば、「変更があった部分だけ」をビルド対象にできます。
変更があったパッケージ（と、それに依存するパッケージ）だけをテストする
pnpm test –filter …[origin/main]
このコマンド一つで、メインブランチと現在のブランチの差分を検出し、影響範囲だけを精密にテストします。これにより、数十分かかっていたCIが数分で終わるようになることも珍しくありません。
—
まとめ：開発者のための投資
pnpm Workspace を導入することは、単なるパッケージマネージャーの変更ではありません。「依存関係の管理を機械に委ね、自分はコードの本質に集中する」という開発思想へのシフトです。
- インストール: `npm i -g pnpm`
- 動作確認: `pnpm install` して、`node_modules` の中身を覗いてみてください。これまでの `npm` とは全く異なる、美しく整理されたリンク構造に驚くはずです。
この構成を一度構築してしまえば、新規プロジェクトの追加やライブラリの分割が恐ろしく簡単になります。今日からあなたのプロジェクトを「モノレポ」という強固な城壁で守り、開発のスピードを加速させていきましょう。
何か分からないことがあれば、いつでも聞いてください。設計レベルから一緒に考えていきましょう。