Skip to content
Tutorials Center
My learning

Topics

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).

TypeScript
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

TypeScript require from an ES module file

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.

TypeScript Writing and requiring a CommonJS file

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

TypeScript
// 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, exports and __dirname are not defined at run time, even though @types/node declares them globally, so typeof require compiles and then evaluates to "undefined". Use createRequire or import.meta.dirname.
  • export = combined with other export statements in the same file is an error.
  • Each file is evaluated once; require caches the result by resolved filename, so repeated calls return the same object.

Usage notes

  • A plain require() call is not type-checked. Prefer import syntax and let the compiler emit CommonJS if you need that format, so you keep full types.
  • Under module: "nodenext", a .ts file is CommonJS only if the nearest package.json lacks "type": "module" (or says "commonjs"). Mixed projects use .cts and .mts to be explicit.
  • Modern Node can require() ES modules that have no top-level await, so CommonJS code can often load an ES-only package. The reverse, import of CommonJS, is always allowed and is covered in ESM and CJS interop.
  • module.exports and exports start as the same object. Assigning a new value to exports breaks the link, which is the classic mistake; assign to module.exports instead.
  • Avoid import x = require() in new code unless you must support a CommonJS-only target. The option erasableSyntaxOnly rejects it because it is not plain type syntax.