ESMとCJSのデュアルパッケージ出力

ESM（ECMAScript Modules）は、importとexport構文を使用する、公式のJavaScriptモジュール標準です。ESMは静的に解析できるため、バンドラーはビルド時に実際に使用されるエクスポートを正確に判断でき、ツリーシェイキングが可能になります。最新のブラウザーとNode.jsは、どちらもESMをネイティブにサポートしています。

CJS（CommonJS）は、require()とmodule.exports構文を使用します。これはNode.jsで最初に採用されたモジュールシステムであり、古いNode.js環境、Jest（従来CJSを使用していました）、require()を使用するコードとの互換性のために、現在も必要とされています。CJSは動的に評価されるため、ツリーシェイキングが難しくなります。

最新のnpmパッケージでは、互換性を最大限に高めるため、ESMとCJSの両方を提供するべきです。ESM利用者（Vite、Next.js、最新のバンドラー）は、ツリーシェイキング可能なインポートを利用できます。CJS利用者（古いNode.jsスクリプト、設定なしのJest）は、require()との互換性を利用できます。package.jsonのexportsフィールドによって、Nodeとバンドラーが使用する形式を判断します。

package.jsonのexportsフィールドは、条件付きエントリーポイントを定義する最新の方法です。例：{ '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }。バンドラーとNode.js 12以降はexportsを読み取り、適切な形式を自動的に選択します。

古いツールはexportsフィールドを理解できません。互換性のため、次の設定も行ってください。mainはCJS出力を指すように設定します（従来のNode requireのフォールバック）。moduleはESM出力を指すように設定します（webpackやrollup向けのヒントで、標準ではありませんが広くサポートされています）。最新のツールはexportsを優先し、古いツールはmain/moduleにフォールバックします。

package.jsonで"type": "module"を設定すると、パッケージ内のすべての.jsファイルがESMとして扱われます。デュアル形式で提供する場合は、明示的な拡張子が必要になります。typeがmoduleの場合はESMファイルに.mjs、CJSファイルに.cjsを使用します。逆の構成にすることもできます。tsupがこの処理を自動的に行います。

.mjs（ESM）と.cjs（CJS）のファイル拡張子を使用すると、typeフィールドの設定にかかわらず形式を明示できます。これにより曖昧さを避けられます。tsupでは、formatが['esm', 'cjs']でtypeフィールドを設定していない場合、index.js（ESM）とindex.cjs（CJS）を出力できます。これは最も一般的な規約に沿った形式です。

パッケージがESMとCJSの両方の形式を提供すると、利用者側のバンドラーが同じプロセス内で両方のバージョンを読み込む場合があります。たとえば、メインアプリではESM版、JestのテストではCJS版が読み込まれるケースです。パッケージがモジュールレベルの状態（Reactコンテキストなど）を持っていると、両方のインスタンスが独立した状態を持つことになります。これがデュアルパッケージの危険性です。

この危険性を軽減するには、ライブラリからモジュールレベルの状態を排除し（シングルトンパターンを使用しない）、exportsの条件を正確に設定して1つの形式だけが読み込まれるようにし、テストではESMを使用するようバンドラーを設定することを文書化してください。この危険性が主に問題となるのは、共有シングルトンを持つライブラリです。

ビルド後に両方の形式が機能することを確認してください。CJSのテスト：node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)"。ESMのテスト：node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)"。公開前に、どちらもエラーなしで解決できることを確認してください。

exportsフィールドは複数のエントリーポイントをサポートします：{ '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }。利用者は'your-lib'または'your-lib/utils'からインポートするだけで、適切な形式を利用できます。

ライブラリのpackage.jsonにあるexportsフィールドの主な目的は何ですか？

ESMはimport/exportを使用し、ツリーシェイキングを可能にします。CJSはrequire()を使用し、Node.jsとの互換性を提供します。package.jsonのexportsフィールドでimport/require条件を指定し、両方の形式を提供してください。従来のフォールバックにはmain（CJS）とmodule（ESM）を使用します。.mjs/.cjs拡張子またはtype: moduleで形式を明示します。ビルド後にnode CLIで両方の形式をテストしてください。シングルトン状態を持つ場合は、デュアルパッケージの危険性に注意が必要です。