Node.js における ES モジュールと CommonJS

概要

CommonJS（CJS）は Node が元から持つモジュールシステムである。require() は実行時に同期的に読み込み、モジュールは module.exports に代入したものをエクスポートする。ES モジュール（ESM）は言語の標準である。import と export は静的で、モジュール本体の実行前に解決され、読み込みは非同期である。トップレベルの await が許され、import.meta はモジュールのメタデータを持つ。Node はファイルごとに判断し、.mjs は常に ESM、.cjs は常に CJS、.js は最も近い package.json の "type" フィールドに従う。"type" がないファイルは、パッケージの文書では曖昧なファイルとされる。現在の Node はまず CommonJS として実行し、パーサーが ES モジュール構文を見つけた場合は ES モジュールとして再評価する。これが構文検出である。古いバージョンは単に CommonJS として扱う。ESM の文書には、ESM にないもの（require、module.exports、__filename、__dirname）と代替手段である import.meta.filename、import.meta.dirname、import.meta.resolve()、module.createRequire() が列挙されている。ESM は CommonJS をインポートでき、デフォルトインポートは module.exports になる。また、現在の Node は、依存グラフにトップレベルの await がなければ、ES モジュールを require() で読み込める。

重要な理由

二つの方式の混在は、Node プロジェクトで最もよくある起動エラーの原因となる。「Cannot use import statement outside a module」、ERR_REQUIRE_ESM、exports is not defined などである。テストランナー、TypeScript の出力、バンドラーにはそれぞれ独自のモジュール設定があり、不整合はビルド時ではなく実行時に失敗を引き起こす。

適用方法

• 新しいコードでは package.json に "type": "module" を設定し、全体を ESM で書く。CommonJS のままにする必要がある少数のファイルには .cjs を付ける。
• ESM の相対インポートにはファイル拡張子が必要である（./util.js、./dir/index.js）。リゾルバーは推測しない。
• JSON は属性を付けてインポートする。import cfg from "./cfg.json" with { type: "json" } を使う。
• 両形式を配布するライブラリでは、import と require の条件を持つ "exports" を宣言する。その前に、パッケージの文書と、そこからリンクされるデュアルパッケージのサンプルリポジトリを読む。両方のエントリーポイントから読み込んだパッケージは、独立したモジュール状態を持つ二つの実体として存在する。これがデュアルパッケージの危険性である。
• ブラウザーでは、モジュールスクリプトを text/javascript などの JavaScript MIME タイプで配信しなければならない。MDN は、別のタイプで配信された .mjs ファイルに対する厳密な MIME タイプ検査のエラーを説明している。

落とし穴

循環インポートの動作は異なる。ESM のバインディングは現在の値を反映するが、早期に読むと未初期化の場合がある。トップレベルの await を使う ESM を require() すると ERR_REQUIRE_ASYNC_MODULE が送出されるため、代わりに import() を使う。"type": "module" のパッケージに require 呼び出しを出力するコンパイラーは、読み込み時に失敗するコードを生成する。コンパイラーのモジュール出力設定を実行環境とそろえる。