「exports」フィールドの深淵：Node.jsモジュール解決の地獄から脱出するアーキテクトの視点
npmエコシステムにおいて、`exports`フィールドの導入は「革命」であると同時に、多くの開発者を「Module not found」という名の迷宮に突き落としました。
かつての`main`フィールドは、広大なファイルシステムを無差別にさらけ出す「無法地帯」でした。しかし、`exports`は「カプセル化」という強力な境界線を引きます。これを理解せずにモジュールを設計することは、航空機の操縦桿を握らずに離陸するようなものです。
本稿では、テックリードとして、なぜこの設定が現代のフロントエンド開発において不可欠なのか、そしてどう設定すれば「依存関係の悪夢」を回避できるのかを解き明かします。
—
1. なぜ「exports」が必要なのか：内部構造の隠蔽と型安全
従来、ライブラリ内部のファイルを`import { func } from ‘my-lib/dist/utils/helper’`のように直接インポートさせる行為が横行していました。これは、ライブラリ作者が「内部実装を変更した瞬間に、依存している全クライアントを破壊する」というリスクを抱えることを意味します。
`exports`は、「パッケージの公開APIをホワイトリスト化する」仕組みです。これにより、開発者は「公開して良いファイル」と「内部だけで使うファイル」を明確に分離でき、Node.jsのモジュール解決プロセスを高速化・厳格化できます。
—
2. 実践：CommonJSとESMの共存を制するベストプラクティス
`exports`設定で最も陥りやすい罠は、Node.jsがモジュールを解決する際、「先頭から順番にマッチングを試みる」という挙動を理解していないことです。
以下は、モダンなライブラリ開発における最も堅牢な`package.json`の構成例です。
{
“name”: “my-awesome-lib”,
“version”: “1.0.0”,
“type”: “module”, // パッケージ全体をESMとして扱う宣言
“exports”: {
“.”: {
// ユーザーの環境がESMをサポートしている場合はこちらを優先
“import”: “./dist/index.mjs”,
// CommonJS環境（require）の場合はこちらへフォールバック
“require”: “./dist/index.cjs”,
// 型定義ファイル（TypeScriptユーザー向け）
“types”: “./dist/index.d.ts”
},
// サブパスのエクスポートを制御し、内部構造を隠蔽する
“./utils”: {
“import”: “./dist/utils.mjs”,
“require”: “./dist/utils.cjs”
}
}
}
この設定の肝
- `import`と`require`の分離: Node.js 12+では、この順序が重要です。条件がマッチした時点で探索を終了するため、必ず「より具体的な条件」を上に記述してください。
- サブパスの制限: ここで指定されていないパス（例: `my-awesome-lib/dist/private.js`）は、Node.jsのランタイムによってアクセスが拒否されます。 これにより、ライブラリの破壊的変更を未然に防ぐ「境界線」が完成します。
—
3. 開発スピードを極限まで高める「神ツール」と設定
この複雑な`exports`の挙動を、デバッグなしで保証するためのツールチェーンを紹介します。
推奨ツール：`publint`
`exports`の設定ミスは、インストールした瞬間にではなく、クライアント環境で初めて発覚します。これを防ぐために、ビルドパイプラインに`publint`を組み込んでください。
プロジェクトルートで実行
npx publint
このツールは、`package.json`の`exports`が実際に解決可能か、条件が正しく機能しているかを静的解析でチェックします。
VS Code設定：`exports`の可視化
チーム全員が同じ挙動を把握するために、`.vscode/settings.json`でモジュール解決の警告を強化します。
{
// モジュール解決に失敗した際、警告を出す
“javascript.validate.enable”: true,
“typescript.tsdk”: “node_modules/typescript/lib”,
// インポートパスがexportsを尊重しているか補完を制御
“typescript.preferences.importModuleSpecifier”: “non-relative”
}
—
4. チーム開発における「共有ルール」
「exportsが動かない！」というトラブルの9割は、ビルドツール（Webpack, Vite, Rollup）の設定とNode.jsのネイティブ解決の乖離です。
黄金ルール：
1. `main`フィールドは過去の遺物として残す: 古いツールチェーンへの互換性のため、`exports`と併記すること。ただし、`exports`を正しく設定すれば、現代的な環境では無視されます。
2. `package.json`をGitの変更管理の最優先事項にする: `exports`を変更した際は、必ず依存関係を持つ全マイクロサービスの統合テストをトリガーしてください。
3. ローカル検証には`yalc`を使う: `npm link`はシンボリックリンク特有の罠（Node.jsのモジュール解決パスの重複）を生みます。ローカルでのライブラリ検証には、パッケージを一度ローカルキャッシュとして展開する`yalc`を使い、本番環境と同一の解決挙動を再現してください。
—
最後に：アーキテクトからの提言
`exports`フィールドの導入は、一時的な「面倒くささ」をもたらします。しかし、それは「将来の自分たちが抱えるかもしれない、深夜2時のデバッグ地獄」を先払いして解決していることと同義です。
モジュール解決の挙動を制御することは、アプリケーションの堅牢性を担保する土台です。この記事を読んだ今日、あなたのプロジェクトの`package.json`を今一度見直し、不要な公開パスを閉じ、安全なカプセル化を実装してください。それこそが、大規模開発をスケールさせる唯一の道なのです。