TypeScriptにおいてCommonJSとES Moduleの両方に対応するパッケージを作る #JavaScript

はじめに

最近ではNode.jsのライブラリでも、pure ESMの考え方でES Moduleのみでしか利用できないものも出てきている。とはいえ、npm-esm-vs-cjsというリポジトリのデータによると、以下のようにCommonJSのライブラリのほうが圧倒的に多く、ES Moduleのみはまだ10％程度しかない（みたい）。

そこで、今回はライブラリを公開する際に、CommonJSとES Moduleの両方をサポートするようなプロジェクトの設定についてみていきたいと思う。

※前提として、今回は1つのTypeScriptファイルからCommonJS・ES Moduleの両方に対応するJavaScriptファイルを作成することを考える（ファイル拡張子を".mts"や".cts"にして、コンパイル後のファイル拡張子を変えることでCommonJS・ES Moduleに対応する方法ではない）。そのため、コンパイル後のコードとセットで"type"を指定するためのpackage.jsonが必要になる。ファイルの拡張子を変える事でデュアルパッケージにする方法はNative ESM / 擬似 ESM Dual package （module:node12 以降）などを参照。

その前に

CommonJSとES Moduleの両方をサポートする、言わゆるデュアルパッケージの設定をする前に、既存の設定についてみておく。

今回は2023年7月25日時点で、pure ESMのライブラリとして公開されているretry-axiosを題材にしてやってみたいと思う。

このライブラリのpackage.jsonの設定は、"type": "module"になっており、そのためTypeScriptをコンパイル後のJavaScriptは***.jsとなりES Moduleの環境でしか利用できない状態になる。

※ES Moduleのみでしか利用できないライブラリをCommonJSにコンパイルする環境のTypeScriptで利用すると、以下のようにエラーになる。

$ yarn tsc -p .
yarn run v1.22.19
$ tsc -p .
srv/app.ts:3:29 - error TS1479: The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("retry-axios")' call instead.
  To convert this file to an ECMAScript module, change its file extension to '.mts' or create a local package.json file with `{ "type": "module" }`.

3 import * as retryAxios from 'retry-axios';
                              ~~~~~~~~~~~~~


Found 1 error in srv/app.ts:3

デュアルパッケージ（CommonJS・ES Moduleの両方をサポートするよう）に設定を変更する

はじめにでも少し触れたが、今回は1つのTypeScriptファイルをコンパイルして作成されるJavaScriptでCommonJS・ES Moduleの両方をサポートするようにする。そのため、コンパイル後のコードは、例えば以下のようなディレクトリ構成になる必要がある。

- package.json          // { "type": "module" }
- index.ts              
- tsconfig.json         // output to `module` directory
- tsconfig.cjs.json     // output to `cjs` directory
- cjs/
    - package.json      // { "type": "commonjs" }
    - index.js          // Node.js treat it as CommonJS module
- module/
    - package.json      // { "type": "module" }
    - index.js          // Node.js treat it as ESModule

これはissueで議論されているように、コンパイル後のJavaScriptファイルの拡張子をいじれるようにする機能がコンパイラにはないため、拡張子ではないもの（今回だとpackage.json）でCommonJS・ES Moduleの両方をサポートするような設定にする必要がある。

今回は上記のようにそれぞれのディレクトリにpackage.jsonを配置することで、デュアルパッケージを実現してみようと思う。

まずは、CommonJSのJavaScriptを出力するためのtsconfig.cjs.jsonを追加で作成する。基本的には、ES ModuleのJavaScriptを出力させるtsconfig.jsonの設定を踏襲して、モジュールのターゲットと出力先だけを変えればいいので、以下のようなシンプルな設定になるだろう。

tsconfig.cjs.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "build/cjs",
  }
}

続いて、package.jsonの設定を変える。以下のようにすればいい。

package.json

{
  ...
  "type": "module",
  "exports": {
    ".": {
      "import": {
        "types": "./build/src/index.d.ts",
        "default": "./build/src/index.js"
      },
      "require": {
        "types": "./build/cjs/src/index.d.ts",
        "default": "./build/cjs/src/index.js"
      },
      "default": "./build/cjs/src/index.js"
    }
  },
  "types": "./build/src/index.d.ts",
  "main": "./build/cjs/src/index.js",
  "module": "./build/src/index.js",
  ...
}

元の設定との差分は以下のスクショを参照。

上記の設定について少し補足する。

main
古いバージョンのNode.jsのためのCJSフォールバックのための設定
module
Node.jsでは採用されなかった機能だが、バンドラーでは使われているもので、ES Moduleのエントリーポイントを示すための設定。詳細についてはesbuildなどのドキュメントを参照。
types
パッケージにバンドルされた型定義ファイルを示すための設定
exports
条件に応じてエントリーポイントを切り替えるための設定。importであればimportが、requireであればrequireが利用される（Conditional exportsなども参照）。

このpackage.jsonの設定により、CommonJS・ES Moduleのそれぞれでエントリーポイントを分けることができるので、デュアルパッケージを実現できる。

続いて、コンパイル後のディレクトリ構成は以下になるが、それぞれにpackage.jsonを作成するための設定を行う。

$ tree . -I "node_modules"
.
├── build
│   ├── cjs
│   │   ├── package.json // <- これ
│   │   └── src
│   │       ├── index.d.ts
│   │       ├── index.js
│   │       └── index.js.map
│   ├── package.json // <- これ
│   └── src
│       ├── index.d.ts
│       ├── index.js
│       └── index.js.map
...

今回はtsconfig-to-dual-packageを利用する。このツールは、デュアルパッケージ用のpackage.jsonをtsconfigのoutDirに追加してくれる。

あとは、コンパイルをするためのscriptsを定義して、コンパイルを実行すればいい。

package.json

{
    "scripts": {
    ...
    "compile": "tsc -p . && tsc -p tsconfig.cjs.json && tsconfig-to-dual-package",
}

これでデュアルパッケージのための設定は完了になる。

※今回はtsconfig-to-dual-packageを利用してCommonJS・ES Moduleのそれぞれにpackage.jsonを追加したが、単純に{"type": "module"}などのモジュール設定のみのpackage.jsonを追加するでも対応は可能。stripe-nodeではそのような方法をとっている。

※デュアルパッケージを実現する方法は、https://github.com/microsoft/TypeScript/issues/49462#issuecomment-1633279027 などを参照。今回みてきたようなpackage.jsonを利用する方法以外にも、babelを利用したりrollupを利用する方法もあるだろう。

まとめとして

今回はCommonJS・ES Moduleの両方に対応するパッケージを作成するための方法として、package.jsonのtypeフィールドが異なるディレクトリを作成して、それをexportsで公開する方法をみてきた。今回はpure ESMのパッケージをCommonJSにも対応させる、ということをやったが、できればNativeでES Moduleを利用する世界が来ると楽になるだろうなと感じた（どちらにも対応するデュアルパッケージを作成するという必要もなくなるので）。

※今回の対応をPRで出してみたが、それは以下。