Node.jsの「ESM移行」という深淵：なぜ今、CommonJSと決別し「ハイブリッド」を目指すべきなのか
こんにちは。開発環境の設計を専門とするエンジニアとして、今日はNode.jsにおける「ES Modules (ESM)」という、現代JavaScript開発の最大の転換点についてお話しします。
多くのエンジニアが「なんとなく `import` を使ったら動いた」で済ませていますが、実はNode.jsの内部では、歴史ある `CommonJS (CJS)` との間に見えない壁が存在します。この壁を理解せず適当に移行すると、CI/CDで謎のビルドエラーに苦しんだり、ランタイムでモジュールのロード順序に翻弄されることになります。
今日は、「堅牢で、かつ将来性のあるハイブリッドパッケージ」を構築するための、本質的なアーキテクチャを伝授します。
—
1. なぜ「ハイブリッド」が必要なのか？
Node.jsの世界には現在、二つの流儀が共存しています。
- CommonJS (CJS): `require()` と `module.exports` を使う、Node.jsの古き良き伝統。
- ES Modules (ESM): `import` と `export` を使う、ブラウザ標準およびECMAScript規格。
もしあなたがライブラリを作成するなら、「どちらの環境からも呼び出せる」ようにする必要があります。これを怠ると、利用者はあなたのライブラリを使うためだけにプロジェクト全体を ESM 化せざるを得なくなります。これは破壊的な変更であり、ユーザー体験を著しく損ないます。
—
2. 核心設定：package.jsonの「exports」マップ
ハイブリッド構成の鍵は、`package.json` の `exports` フィールドです。これを設定することで、Node.jsに対して「このパスにアクセスされたら、このファイルを渡せ」というルーティングを定義できます。
{
“name”: “my-hybrid-library”,
“version”: “1.0.0”,
“type”: “module”, // プロジェクト全体をデフォルトでESMとして扱う
“exports”: {
“.”: {
“import”: “./dist/index.js”, // import で呼ばれたらESM版を返す
“require”: “./dist/index.cjs” // require で呼ばれたらCJS版を返す
}
}
}
なぜこの設定が「震えるほど」重要なのか？
従来、多くのライブラリは単一のファイルを読み込ませていましたが、これでは「ツリーシェイキング（不要なコードの削除）」が効きません。`exports` を適切に設定することで、Bundler（WebpackやVite）は「ユーザーが import を使っているなら ESM のファイルを読み込もう」と最適化を判断でき、結果としてアプリケーションのバンドルサイズが劇的に縮小します。
—
3. 実践：ハイブリッドな「Hello World」を構築する
実際に動作を確認してみましょう。ポイントは「拡張子による明示」です。
手順1: ファイル構成
.
├── package.json
├── src/
│ └── index.js # ESMソース
└── dist/ # ビルド後の成果物
手順2: ソースコード (src/index.js)
// ESMの書き方
export const greet = (name) => `Hello, ${name}!`;
手順3: ビルド生成物の作成
ここが「罠」のポイントです。Node.jsに「これはCJSだ」と認識させるには、拡張子を `.cjs` にする必要があります。
// dist/index.cjs (CommonJS用に変換したもの)
module.exports.greet = (name) => `Hello, ${name}!`;
—
4. 開発効率を最大化する「移行戦略」
これから ESM に完全移行したい場合、以下の3ステップを守ってください。
1. 段階的移行: `package.json` に `”type”: “module”` を書く前に、まず拡張子を `.mjs` に変えて動作検証する。
2. デュアルパッケージの自動化: 手動で `.cjs` を作るのはナンセンスです。`tsup` や `microbundle` といったツールを使い、`package.json` のビルドスクリプトに組み込みましょう。
推奨されるビルド設定 (tsupの例):
インストール
npm install tsup -D
package.jsonに追加
“scripts”: {
“build”: “tsup src/index.js –format cjs,esm –dts”
}
この一行で、ESM と CJS の両方を生成し、型定義ファイル（.d.ts）まで自動で生成されます。これが今の時代の「標準的な開発効率」です。
—
最後に：アーキテクトからのアドバイス
ESMへの移行は、単なる構文の書き換えではありません。「依存関係の解決戦略」の刷新です。`import` が静的解析を前提としているのに対し、`require` は動的です。この差を理解し、`exports` でパスを管理できるようになると、あなたはもう「Node.jsの作法」に迷うことはなくなります。
まずは、小さなライブラリやツールから `exports` を使った構成を試してみてください。最初は少し煩雑に感じるかもしれませんが、大規模なプロジェクトになればなるほど、この規律があなたのコードベースを崩壊から守る「防波堤」になることを約束します。
「動けばいい」から「正しく動く設計へ」。
その一歩が、あなたのエンジニアとしての価値を確実に引き上げますよ。応援しています。