このガイドは、ESモジュールが何であるか、そしてNuxtアプリ（または上流のライブラリ）をESMに対応させる方法を説明します。

背景

CommonJSモジュール

CommonJS (CJS) は、Node.jsによって導入された形式で、分離されたJavaScriptモジュール間で機能を共有することを可能にします（詳細はこちら）。 この構文にすでに馴染みがあるかもしれません：

const a = require('./a')

module.exports.a = a

webpackやRollupのようなバンドラーはこの構文をサポートしており、CommonJSで書かれたモジュールをブラウザで使用することができます。

ESM構文

多くの場合、ESMとCJSの話をするとき、人々はモジュールを書くための異なる構文について話しています。

import a from './a'

export { a }

ECMAScriptモジュール（ESM）が標準になる前（それには10年以上かかりました！）、webpackのようなツールやTypeScriptのような言語でさえ、いわゆるESM構文をサポートし始めました。 しかし、実際の仕様とはいくつかの重要な違いがあります。こちらに役立つ説明があります。

「ネイティブ」ESMとは何か？

あなたは長い間、ESM構文を使ってアプリを書いてきたかもしれません。結局のところ、ブラウザによってネイティブにサポートされており、Nuxt 2では、あなたが書いたすべてのコードを適切な形式（サーバー用にはCJS、ブラウザ用にはESM）にコンパイルしていました。

パッケージにモジュールを追加するとき、状況は少し異なりました。サンプルライブラリはCJSとESMの両方のバージョンを公開し、どちらを使用するか選ばせてくれました：

{
  "name": "sample-library",
  "main": "dist/sample-library.cjs.js",
  "module": "dist/sample-library.esm.js"
}

したがって、Nuxt 2では、バンドラー（webpack）がサーバービルド用にCJSファイル（'main'）を取り込み、クライアントビルド用にESMファイル（'module'）を使用していました。

しかし、最近のNode.js LTSリリースでは、Node.js内でネイティブESMモジュールを使用することが可能になりました。つまり、Node.js自体がESM構文を使用してJavaScriptを処理できるようになったのです。ただし、デフォルトではそうしません。ESM構文を有効にする最も一般的な方法は次の2つです：

• package.json内で"type": "module"を設定し、.js拡張子を使用し続ける
• .mjsファイル拡張子を使用する（推奨）

これはNuxt Nitroで行っていることで、.output/server/index.mjsファイルを出力しています。これにより、Node.jsはこのファイルをネイティブESモジュールとして扱います。

Node.jsコンテキストでの有効なインポートとは？

モジュールをrequireするのではなくimportすると、Node.jsはそれを異なる方法で解決します。たとえば、sample-libraryをインポートすると、Node.jsはそのライブラリのpackage.json内のmainではなく、exportsまたはmoduleエントリを探します。

これは、const b = await import('sample-library')のような動的インポートにも当てはまります。

Nodeは次の種類のインポートをサポートしています（ドキュメントを参照）：

1. .mjsで終わるファイル - これらはESM構文を使用することが期待されます
2. .cjsで終わるファイル - これらはCJS構文を使用することが期待されます
3. .jsで終わるファイル - これらはpackage.jsonに"type": "module"がない限りCJS構文を使用することが期待されます

どのような問題が発生する可能性がありますか？

長い間、モジュールの作成者はESM構文のビルドを生成していましたが、.esm.jsや.es.jsのような慣習を使用しており、それをpackage.jsonのmoduleフィールドに追加していました。これは、webpackのようなバンドラーによってのみ使用されていたため、これまで問題にはなりませんでした。

しかし、Node.jsのESMコンテキストで.esm.jsファイルを持つパッケージをインポートしようとすると、次のようなエラーが発生します：

(node:22145) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
/path/to/index.js:1

export default {}
^^^^^^

SyntaxError: Unexpected token 'export'
    at wrapSafe (internal/modules/cjs/loader.js:1001:16)
    at Module._compile (internal/modules/cjs/loader.js:1049:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    ....
    at async Object.loadESM (internal/process/esm_loader.js:68:5)

また、Node.jsがCJSと考えるESM構文ビルドから名前付きインポートを行った場合にも、このエラーが発生する可能性があります：

file:///path/to/index.mjs:5
import { named } from 'sample-library'
         ^^^^^
SyntaxError: Named export 'named' not found. The requested module 'sample-library' is a CommonJS module, which may not support all module.exports as named exports.

CommonJS modules can always be imported via the default export, for example using:

import pkg from 'sample-library';
const { named } = pkg;

    at ModuleJob._instantiate (internal/modules/esm/module_job.js:120:21)
    at async ModuleJob.run (internal/modules/esm/module_job.js:165:5)
    at async Loader.import (internal/modules/esm/loader.js:177:24)
    at async Object.loadESM (internal/process/esm_loader.js:68:5)

ESMの問題のトラブルシューティング

これらのエラーに遭遇した場合、問題はほぼ確実に上流のライブラリにあります。彼らはNodeによってインポートされることをサポートするためにライブラリを修正する必要があります。

ライブラリのトランスパイル

その間、これらのライブラリをインポートしないようにNuxtに指示することができます。build.transpileに追加してください：

export default defineNuxtConfig({
  build: {
    transpile: ['sample-library']
  }
})

これらのライブラリによってインポートされている他のパッケージも追加する必要があるかもしれません。

ライブラリのエイリアス

場合によっては、ライブラリをCJSバージョンに手動でエイリアスする必要があるかもしれません。例えば：

export default defineNuxtConfig({
  alias: {
    'sample-library': 'sample-library/dist/sample-library.cjs.js'
  }
})

デフォルトエクスポート

CommonJS形式の依存関係は、module.exportsまたはexportsを使用してデフォルトエクスポートを提供できます：

module.exports = { test: 123 }
// または
exports.test = 123

このような依存関係をrequireすると通常はうまく動作します：

const pkg = require('cjs-pkg')

console.log(pkg) // { test: 123 }

ネイティブESMモードのNode.js、esModuleInteropを有効にしたTypeScript、およびwebpackのようなバンドラーは、このようなライブラリをデフォルトインポートできる互換性メカニズムを提供します。 このメカニズムはしばしば「interop require default」と呼ばれます：

import pkg from 'cjs-pkg'

console.log(pkg) // { test: 123 }

しかし、構文検出の複雑さや異なるバンドル形式のため、interop defaultが失敗し、次のような結果になる可能性があります：

import pkg from 'cjs-pkg'

console.log(pkg) // { default: { test: 123 } }

また、動的インポート構文を使用する場合（CJSおよびESMファイルの両方で）、常にこの状況が発生します：

import('cjs-pkg').then(console.log) // [Module: null prototype] { default: { test: '123' } }

この場合、デフォルトエクスポートを手動でinteropする必要があります：

// 静的インポート
import { default as pkg } from 'cjs-pkg'

// 動的インポート
import('cjs-pkg').then(m => m.default || m).then(console.log)

より複雑な状況を処理し、より安全にするために、Nuxtではmllyを内部的に使用しており、名前付きエクスポートを保持できます。

import { interopDefault } from 'mlly'

// 形状が { default: { foo: 'bar' }, baz: 'qux' } であると仮定
import myModule from 'my-module'

console.log(interopDefault(myModule)) // { foo: 'bar', baz: 'qux' }

ライブラリ作成者ガイド

良いニュースは、ESM互換性の問題を修正するのは比較的簡単だということです。主に2つのオプションがあります：

1. ESMファイルの名前を.mjsで終わるように変更することができます。

   これは推奨される最も簡単なアプローチです。 ライブラリの依存関係やビルドシステムに関する問題を解決する必要があるかもしれませんが、ほとんどの場合、これで問題は解決します。また、CJSファイルの名前を.cjsで終わるように変更することも推奨されます。これにより、より明示的になります。

2. ライブラリ全体をESM専用にすることを選択できます。

   これは、package.jsonに"type": "module"を設定し、ビルドされたライブラリがESM構文を使用することを確認することを意味します。ただし、依存関係に問題が発生する可能性があり、このアプローチではライブラリがESMコンテキストでのみ消費されることを意味します。

移行

CJSからESMへの最初のステップは、requireの使用をimportに更新することです：

module.exports = ...

exports.hello = ...

const myLib = require('my-lib')

ESMモジュールでは、CJSとは異なり、require、require.resolve、__filename、__dirnameのグローバルは使用できず、import()およびimport.meta.filenameに置き換える必要があります。

import { join } from 'path'

const newDir = join(__dirname, 'new-dir')

const someFile = require.resolve('./lib/foo.js')

ベストプラクティス

• デフォルトエクスポートよりも名前付きエクスポートを優先してください。これにより、CJSの競合が減少します。（デフォルトエクスポートセクションを参照）

• Nitroポリフィルを必要とせずにブラウザやエッジワーカーでライブラリを使用できるようにするため、Node.jsのビルトインやCommonJSまたはNode.js専用の依存関係にできるだけ依存しないようにしてください。

• 条件付きエクスポートを使用して新しいexportsフィールドを使用してください。（詳細はこちら）

{
  "exports": {
    ".": {
      "import": "./dist/mymodule.mjs"
    }
  }
}