CommonJS vs ESモジュール：`package.json`の`exports`フィールドでTypeScriptモジュールを正しくインポートする方法

Node.js と TypeScript における package.json の exports フィールドの問題

しかし、TypeScript と Node.js を一緒に使用する場合、package.json ファイルの exports フィールドに関する問題が発生することがあります。 この問題は、TypeScript で記述されたモジュールを Node.js アプリケーションでインポートしようとするときに発生します。

package.json ファイルの exports フィールドは、Node.js アプリケーションがモジュールをどのようにインポートできるかを定義するために使用されます。 従来の CommonJS モジュールの場合、exports フィールドはオブジェクトとして定義され、モジュール内のエクスポートされたメンバーを列挙します。

一方、TypeScript モジュールは、ES モジュール形式でエクスポートされることが多くなります。 ES モジュール形式では、exports フィールドはファイルパスとして定義され、エクスポートされたメンバーを定義するファイルへの参照を提供します。

この違いにより、Node.js アプリケーションが TypeScript モジュールをインポートしようとするときに問題が発生することがあります。 Node.js は従来の CommonJS モジュールの形式を期待しているため、ES モジュール形式の exports フィールドを正しく解釈できない場合があります。

解決策

この問題を解決するには、以下のいずれかの方法を使用できます。

ts-node を使用する

ts-node は、TypeScript ファイルを直接実行するための Node.js パッケージです。 ts-node を使用すると、Node.js は TypeScript ファイルを JavaScript にコンパイルし、実行することができます。 これにより、exports フィールドに関する問題を回避できます。

tsc を使用して JavaScript ファイルを生成する

tsc は、TypeScript コンパイラです。 tsc を使用して、TypeScript ファイルを JavaScript ファイルにコンパイルすることができます。 コンパイルされた JavaScript ファイルには、従来の CommonJS 形式の exports フィールドが含まれます。

rollup などのバンドルツールを使用する

rollup は、JavaScript モジュールをバンドルするためのツールです。 rollup を使用して、TypeScript モジュールを ES モジュール形式から CommonJS モジュール形式に変換することができます。

# TypeScript ファイルを実行する
ts-node index.ts

# TypeScript ファイルを JavaScript ファイルにコンパイルする
tsc index.ts

# 生成された JavaScript ファイルを実行する
node index.js

例 3: rollup を使用して CommonJS モジュールを生成する

# TypeScript モジュールを ES モジュール形式にバンドルする
rollup -i index.ts -o index.es.js

# 生成された ES モジュールファイルを CommonJS モジュールに変換する
rollup -i index.es.js -o index.cjs.js

# 生成された CommonJS モジュールを実行する
node index.cjs.js

上記はあくまでも例であり、具体的な解決策はプロジェクトの要件によって異なる場合があります。

TypeScript 4.1 以降では、package.json ファイルの exports フィールドと併せて type フィールドを使用することができます。 type フィールドは、モジュールの型定義ファイルへのパスを指定します。 これにより、TypeScript コンパイラはモジュールの型情報を取得し、より正確な型チェックを行うことができます。

例

{
  "name": "my-package",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": ["dist/index.d.ts"],
  "exports": {
    "./lib/math": "./lib/math.js"
  }
}

paths フィールドを使用する

TypeScript 4.1 以降では、package.json ファイルの paths フィールドを使用することができます。 paths フィールドは、モジュール名のエイリアスを定義します。 これにより、モジュールをより短い名前でインポートすることができます。

{
  "name": "my-package",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": ["dist/index.d.ts"],
  "exports": {
    "./lib/math": "./lib/math.js"
  },
  "paths": {
    "@math/*": ["lib/*"]
  }
}

resolve オプションを使用する

TypeScript コンパイラは、resolve オプションを使用して、モジュールの解決方法をカスタマイズすることができます。 このオプションを使用して、package.json ファイルの exports フィールドを無視するようにコンパイラに指示することができます。

{
  "compilerOptions": {
    "resolve": {
      "main": ["dist/index.js"],
      "alias": {
        "@math/*": ["lib/*"]
      }
    }
  }
}

注意事項