esModuleInterop
別名: esModuleInterop フラグ
tsconfig のコンパイラオプションの一つ。
CommonJS モジュールを ES Modules の import 構文で読むときの食い違いを埋め、default エクスポートを持たないモジュールを import x from の形で扱えるようにする。
公開: 更新:
定義
esModuleInterop は TypeScript の tsconfig.json で指定するコンパイラオプションで、CommonJS 形式のモジュールを ES Modules の import 構文で扱うときの食い違いを埋める。
有効にすると allowSyntheticDefaultImports も同時に有効になり、default エクスポートを持たない CommonJS モジュールを import express from "express" の形で読める。
詳細
CommonJS の module.exports は「モジュール全体が 1 つの値」であり、ES Modules の名前空間オブジェクトとは構造が違う。
esModuleInterop が無いと TypeScript は import * as x を module.exports そのものに対応させるため、関数やクラスを丸ごとエクスポートしているモジュールでは仕様上おかしな形になる。
有効にすると __importDefault / __importStar というヘルパーが出力に加わり、ES Modules と同じ意味になるよう変換される。
公式リファレンス(新しいタブで開く)は推奨値を true とする。
TypeScript 5.x までの既定値は module が node16 / nodenext / preserve のときだけ true で、commonjs では false である。
TypeScript 6.0 からは既定で常に有効になり、false の指定は非推奨のエラー(TS5107)になる(TypeScript 6.0 のリリースノート(新しいタブで開く))。"ignoreDeprecations": "6.0" を付けると 6.0 では false のまま効き続け、指定そのものが受け付けられなくなる(TS5108)のは 7.0 からである。
よくある誤解
- 型エラーが消えても、実行時に動くとは限らない。
allowSyntheticDefaultImportsだけを有効にすると型検査だけが通り、出力コードは変わらないため実行時にundefinedになることがある。 - ESM に移行しても、この問題と無関係にはならない。
依存パッケージが CommonJS である限り、相互運用の問題は残る。
関連
TS1259(esModuleInterop flag)が消えない が直接の症状で、Jest で TypeScript が Unexpected token になる でも ts-jest に渡す tsconfig として関わる。