npmワークスペースで実現する「疎結合」の極意：マルチパッケージ開発の罠を突破する
こんにちは。開発環境の深淵を覗き込み、エンジニアの生産性を最大化することを生業としているアーキテクトです。
フロントエンドの規模が拡大するにつれ、単一の巨大なレポジトリ（モノレポ）で複数のパッケージを管理したくなるのは必然です。しかし、`npm workspaces` を安易に導入し、「なんとなく動いた」状態で放置すると、開発環境と本番環境で挙動が異なるという悪夢に直面します。
今回は、単なるコマンドの紹介ではなく、npmが内部でどう依存を解決し、なぜ `exports` フィールドが「パッケージ間の疎結合」において最強の武器になるのかを解説します。
—
1. なぜ npm workspaces なのか：開発の質を変える「リンク」の魔法
npm workspaces の真価は、複数のパッケージを一つのプロジェクト内で管理する利便性以上に、「開発中のパッケージを、あたかもインストール済みの依存パッケージのように扱える」という点にあります。
通常、npmは `node_modules` にパッケージをダウンロードしますが、ワークスペースを使うと、内部的にシンボリックリンクが張られます。これにより、Aパッケージを修正した瞬間、それを参照しているBパッケージにも変更が即座に反映されます。
セットアップの鉄則
まず、ルートディレクトリに `package.json` を作成し、ワークスペースを定義します。
{
“name”: “my-monorepo”,
“private”: true, // ルートパッケージを公開対象から除外する必須設定
“workspaces”: [
“packages/” // packages配下すべてをワークスペースとして認識
]
}
この `private: true` を忘れると、npmはルートディレクトリ自体をパッケージとして公開しようとします。これは初心者が最初に陥る致命的なミスです。
—
2. 開発とビルドの「乖離」という罠
ここで多くのエンジニアが躓くポイントがあります。「開発中は動くのに、ビルドして配布すると動かない」という問題です。
原因は、TypeScriptの型解決やBundlerが、開発時には「生のソースコード」を見に行き、本番ビルド時には「dist配下の成果物」を見に行くという非対称性にあります。これを解決するために、`package.json` の `exports` フィールドを正しく設定する必要があります。
「exports」による疎結合の強制
パッケージの内部構造を隠蔽し、公開したいAPIだけを明示する `exports` フィールドを活用しましょう。
// packages/ui-kit/package.json
{
“name”: “@my-app/ui-kit”,
“exports”: {
“.”: {
“import”: “./dist/index.mjs”, // ESM環境用
“require”: “./dist/index.cjs”, // CJS環境用
“types”: “./dist/index.d.ts” // TypeScriptの型解決用
}
}
}
この設定により、`@my-app/ui-kit` を利用する側のパッケージは、内部コードを直接インポートできなくなります。これにより、「パッケージ間が内部構造に依存しない」という真の疎結合が実現されます。
—
3. HelloWorld：ワークスペース間の連携を確認する
実際に、`core-logic` というパッケージと `web-app` というパッケージを作成し、連携させてみましょう。
手順1: ディレクトリ構造を作成
mkdir -p packages/core-logic packages/web-app
手順2: core-logic の構築
// packages/core-logic/package.json
{
“name”: “@my-app/core-logic”,
“version”: “1.0.0”,
“exports”: { “.”: “./index.js” }
}
`packages/core-logic/index.js` には単純な関数を記述します。
export const greet = () => “Hello from core-logic!”;
手順3: web-app からの利用
`packages/web-app/package.json` に依存を追加します。
{
“name”: “@my-app/web-app”,
“dependencies”: {
“@my-app/core-logic”: “” // バージョン指定を “” にすることでワークスペース内の最新を参照
}
}
動作確認：実行ログ
ルートディレクトリで以下を実行します。
npm install # ワークスペースの依存関係を解決してシンボリックリンクを作成
cd packages/web-app
node -e “import(‘@my-app/core-logic’).then(m => console.log(m.greet()))”
期待される出力:
`Hello from core-logic!`
—
結論：アーキテクトからのアドバイス
npm workspaces を導入する際、最も大切なのは「依存関係の階層構造を意識すること」です。
1. ルートの `package.json` は依存を定義せず、ワークスペースの管理に徹する。
2. `exports` フィールドを使い、パッケージの「出入り口」を厳格に制御する。
3. TypeScriptの `path` マッピング機能と組み合わせ、型解決の齟齬をなくす。
これらをマスターすれば、チームが拡大しても、パッケージ間が複雑に絡み合って身動きが取れなくなる「スパゲッティ・モノレポ」化を防ぐことができます。
開発効率を上げるための環境構築は、最初は少し面倒に感じるかもしれません。しかし、ここで積み上げた規律が、半年後のあなたのコーディング時間を劇的に短縮してくれるはずです。ぜひ、今日からこの設計思想で構築を始めてみてください。応援しています。