Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Concepts and Comparisons

TypeScript with Node.js ES modules

How TypeScript and Node agree on ES modules: package type, .js extensions in imports, nodenext, import.meta, top-level await and importing CommonJS.

Node decides whether a file is an ES module or CommonJS before TypeScript is involved: .mjs and .mts are always ESM, .cjs and .cts are always CommonJS, and .js and .ts follow the "type" field of the nearest package.json ("module" means ESM, anything else means CommonJS). module: "nodenext" makes TypeScript apply the same rules, so what the compiler accepts is what Node will run.

Two habits follow from that. Relative imports in ESM must name a file extension, because Node does not guess. And you write the extension of the output file, not the source file: a TypeScript file util.ts is imported as ./util.js.

JSON
{
  "compilerOptions": {
    "module": "nodenext",
    "target": "es2024",
    "strict": true,
    "outDir": "dist"
  }
}

Try it

TypeScript ESM features that work in a .ts 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 Dynamic import and module namespaces

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.

Rules that matter

  • Relative imports need extensions. import { x } from "./util.js", never "./util". TypeScript resolves ./util.js to util.ts on disk. With --rewriteRelativeImportExtensions you may write ./util.ts and the compiler rewrites it in the output; see rewriteRelativeImportExtensions.
  • Directory imports are not supported. ./lib does not mean ./lib/index.js; write the full path.
  • Package imports honor the exports field of the dependency; see package.json exports.
  • Internal aliases use "imports" in package.json with names that start with #, for example "#db": "./dist/db.js". Unlike paths, Node itself understands them; see paths.
  • No __dirname or __filename. Use import.meta.dirname and import.meta.filename (Node 20.11 and later), or fileURLToPath(import.meta.url).
  • JSON needs an import attribute: import data from "./data.json" with { type: "json" }, plus resolveJsonModule.
  • CommonJS from ESM: import pkg from "cjs-package" gives the whole module.exports as the default export. Named imports work only if Node can detect them statically. See ESM and CommonJS interop.
  • ESM from CommonJS: require() of an ES module works in recent Node versions when the module has no top-level await; TypeScript 5.8 and later allow it under nodenext.

Running TypeScript directly

Node 22.18 and later strip types from .ts files by default, so node main.ts works. Stripping only deletes annotations, so syntax that needs code generation (enums, namespaces with values, parameter properties) is not supported. Turn on erasableSyntaxOnly and verbatimModuleSyntax so the compiler reports such code and keeps type-only imports explicit. Node does not type-check, so keep tsc --noEmit in CI.

Usage notes

  • Pick one module system per package and set "type" explicitly; mixed packages are the main source of "cannot use import statement outside a module" errors.
  • module: "nodenext" implies moduleResolution: "nodenext". Bundler projects use module: "preserve" and moduleResolution: "bundler" instead; see module and moduleResolution.
  • Library authors can ship ESM only, or both formats with conditional exports; each needs matching .d.ts files.
  • Type-only imports (import type) disappear in output and avoid load-order surprises; see Type-only imports.
  • A .ts file is ESM or CJS by the same rules as .js. There is no separate TypeScript setting for it.