Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Language, Modules and Emit Options

TypeScript module option

Reference for the module compiler option: what nodenext, esnext, preserve and commonjs mean, how file extensions decide ESM or CJS, and which to pick.

module tells the compiler which module format to emit and, for the Node-style values, which rules to apply when checking import and require. It answers: should import stay import, or turn into require() calls?

For most projects the choice is simple. Use nodenext (or node20/node18 style presets in newer versions) when the code runs directly in Node. Use esnext or preserve when a bundler such as Vite or esbuild handles the modules afterwards. Use commonjs only for legacy CommonJS output.

JSON
{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" } }

Try it

This site compiles with module: nodenext in an ES module file, which is why these work.

TypeScript ESM features in a nodenext module

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 Using CommonJS from an ES module

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

JSON
{ "compilerOptions": { "module": "nodenext" } }
Value Meaning
nodenext Follows Node's current rules. A .ts file is ESM or CommonJS depending on the nearest package.json "type" (and .mts/.cts force one). Imports of relative files need the .js extension. Implies moduleResolution: nodenext.
node16, node18, node20 Frozen versions of the Node rules, for projects pinned to a Node release.
esnext, es2022, es2020, es2015 Emit ES import/export with no Node-specific checks. Use with a bundler.
preserve Keep each import/export as written and allow mixing styles. Pair with moduleResolution: bundler.
commonjs Emit require/module.exports.
amd, umd, system Legacy loader formats. Rarely needed and deprecated in newer versions.

Usage notes

  • With nodenext, "type": "module" in package.json makes .ts files ES modules (top-level await, import.meta); without it they are CommonJS and import is compiled to require.
  • Importing a relative file in Node ESM needs the output extension: write import "./util.js" even though the source is util.ts. TypeScript maps it back.
  • esnext does not check Node's rules, so code can type-check and still fail in Node because an extension is missing. Prefer nodenext for anything that runs in Node directly.
  • module and moduleResolution should agree. Set both to nodenext, or preserve/esnext with bundler.
  • verbatimModuleSyntax and isolatedModules should be on in bundler setups so each file can be handled alone.
  • Changing module never changes target; they are independent.