TypeScript Reference ยท Modules and Declaration Files
ESM and CommonJS interop in TypeScript
How ES modules and CommonJS work together: default imports of CJS, named export detection, require of ESM, esModuleInterop and allowSyntheticDefaultImports.
ES modules and CommonJS (CJS) can coexist, but they model exports differently. An ES module has a set of named bindings plus an optional default. A CJS module has one value, module.exports, which is often a function or an object. Interop is the set of rules that translates between the two.
For import of a CJS file, Node's rule is simple: default is the whole module.exports, and named imports exist for the properties that Node can detect by scanning the file. TypeScript has to agree with that at compile time, and the options esModuleInterop and allowSyntheticDefaultImports control how it models older CJS packages. In nodenext mode the format of every file is known (from its extension and the package type), and the checker applies Node's real rules.
import express from "express"; // default = module.exports import { readFileSync } from "node:fs"; // named, detected
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
The first run shows the rules. A function export has only default. Assignments such as exports.alpha = 1 are detected, so alpha and beta are real named exports. An object literal assigned to module.exports is only partly detected (here neither gamma nor delta, because their values are not plain identifiers), so read them from default. Recent Node versions also add a module.exports key that holds the whole value.
Syntax
{ "compilerOptions": { "esModuleInterop": true, "allowSyntheticDefaultImports": true } }
| Option | Description |
|---|---|
esModuleInterop |
Emits helpers (__importDefault, __importStar) so that when TypeScript compiles ES imports to CommonJS, import x from "cjs" yields module.exports and import * as ns yields a proper namespace object. Implies allowSyntheticDefaultImports. |
allowSyntheticDefaultImports |
Type-checking only. Lets you write a default import from a module that has no export default, pretending the whole module is the default. Emits nothing. |
module: "nodenext" |
Interop is built in; the checker follows Node's runtime behavior per file. |
Errors and edge cases:
- TS1259: Module can only be default-imported using the
esModuleInteropflag. Seen when interop is off and aexport =module is default-imported. - TS2497: a namespace import of a module that uses
export =for a function or class. - A named import that Node cannot detect statically (for example exports built in a loop) compiles but is
undefinedor a link error at run time. Fall back to the default import and read the property. require()of an ES module fails withERR_REQUIRE_ASYNC_MODULEif it uses top-levelawait, as the second example shows.
Usage notes
- New projects should turn on
esModuleInteropif they compile to CommonJS, and rely onnodenextor a bundler otherwise. Setting it off is rarely right today. allowSyntheticDefaultImportscan claim an import is fine when the runtime disagrees. If you do not use a bundler or Babel doing the interop, it can hide a real bug.import * as ns from "cjs-module"gives a namespace object. Callingns()is invalid in strict ES semantics, even though older TypeScript behavior allowed it without interop.- Node can
require()ES modules when they have no top-levelawait. The result is the namespace object, so the default export is.default. - In a dual world, publish
exportsconditions so each side gets the right file; see package.json exports. - JSON files imported from ESM need attributes; see Importing JSON.