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.
{ "compilerOptions": { "module": "nodenext", "target": "es2024", "strict": true, "outDir": "dist" } }
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.
Rules that matter
- Relative imports need extensions.
import { x } from "./util.js", never"./util". TypeScript resolves./util.jstoutil.tson disk. With--rewriteRelativeImportExtensionsyou may write./util.tsand the compiler rewrites it in the output; see rewriteRelativeImportExtensions. - Directory imports are not supported.
./libdoes not mean./lib/index.js; write the full path. - Package imports honor the
exportsfield of the dependency; see package.json exports. - Internal aliases use
"imports"inpackage.jsonwith names that start with#, for example"#db": "./dist/db.js". Unlikepaths, Node itself understands them; see paths. - No
__dirnameor__filename. Useimport.meta.dirnameandimport.meta.filename(Node 20.11 and later), orfileURLToPath(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 wholemodule.exportsas 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 undernodenext.
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"impliesmoduleResolution: "nodenext". Bundler projects usemodule: "preserve"andmoduleResolution: "bundler"instead; see module and moduleResolution.- Library authors can ship ESM only, or both formats with conditional
exports; each needs matching.d.tsfiles. - Type-only imports (
import type) disappear in output and avoid load-order surprises; see Type-only imports. - A
.tsfile is ESM or CJS by the same rules as.js. There is no separate TypeScript setting for it.