TypeScript Reference ยท Modules and Declaration Files
CommonJS modules in TypeScript
How TypeScript handles CommonJS: require and module.exports, import = require, how .cts and package type decide the format, and loading CJS from ESM.
CommonJS is the module system Node.js used before ES modules existed. A file reads other modules with require() and publishes values by assigning to module.exports or exports. Loading is synchronous, require is an ordinary function, and module, exports, __dirname and __filename are variables Node injects into every file.
TypeScript understands CommonJS in two ways. If you write ES module syntax (import, export) and the compiler is told to emit CommonJS, it translates your code into require and exports calls. If you write the CommonJS forms directly, such as import fs = require("node:fs") or export = value, the compiler checks them and emits them almost unchanged. Which output format a file gets is decided by module, the nearest package.json "type" field and the file extension (.cts is always CommonJS, .mts is always ES module).
import fs = require("node:fs"); // typed require, only valid in a CommonJS file const lazy = require("node:os"); // plain require: the result is any module.exports = { answer: 42 }; // classic export
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.
Syntax
// consuming import fs = require("node:fs"); // typed, CommonJS output only const m = require("./legacy.cjs"); // any, no checking // publishing export = createServer; // module.exports = createServer module.exports = { a: 1 }; // untyped exports.b = 2; // untyped
| Form | Description |
|---|---|
import x = require("m") |
Imports whatever module.exports holds, with its real type. Not allowed when the file is emitted as an ES module. |
export = value |
Sets module.exports. The file may then export nothing else. Consumers use import x = require() or, with interop, import x from. |
require("m") |
Needs @types/node. It returns any unless you add an assertion. |
.cts / .cjs |
Always CommonJS, whatever the package type says. |
Edge cases and errors:
- In an ES module file
require,module,exportsand__dirnameare not defined at run time, even though@types/nodedeclares them globally, sotypeof requirecompiles and then evaluates to"undefined". UsecreateRequireorimport.meta.dirname. export =combined with otherexportstatements in the same file is an error.- Each file is evaluated once;
requirecaches the result by resolved filename, so repeated calls return the same object.
Usage notes
- A plain
require()call is not type-checked. Preferimportsyntax and let the compiler emit CommonJS if you need that format, so you keep full types. - Under
module: "nodenext", a.tsfile is CommonJS only if the nearestpackage.jsonlacks"type": "module"(or says"commonjs"). Mixed projects use.ctsand.mtsto be explicit. - Modern Node can
require()ES modules that have no top-levelawait, so CommonJS code can often load an ES-only package. The reverse,importof CommonJS, is always allowed and is covered in ESM and CJS interop. module.exportsandexportsstart as the same object. Assigning a new value toexportsbreaks the link, which is the classic mistake; assign tomodule.exportsinstead.- Avoid
import x = require()in new code unless you must support a CommonJS-only target. The optionerasableSyntaxOnlyrejects it because it is not plain type syntax.