Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Module Systems

The package.json type field

Reference for the type field in package.json: how "module" and "commonjs" decide how .js files load, how .mjs and .cjs override it and how syntax detection works.

Node.js must decide for every file whether it is an ES module or a CommonJS module before it can run it. For .js files the decision comes from the "type" field of the nearest package.json: "module" means ES module, "commonjs" means CommonJS. The extensions .mjs and .cjs always override the field.

"Nearest" means Node.js starts in the file's folder and walks up until it finds a package.json; that file's type rules every .js file below it, until another package.json with its own setting is found closer to the file.

NODE
{
  "name": "my-app",
  "type": "module"
}

Try it

Node.js The same .js file, two packages

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 process.stdin), it gets the next line from this box.

Node.js Files without any type

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 process.stdin), it gets the next line from this box.

Syntax

NODE
"type": "module" | "commonjs"
Value .js files in the package are...
"module" ES modules. import/export work; require, module, __dirname do not exist.
"commonjs" CommonJS modules.
absent Treated as CommonJS, but with syntax detection (below).

How a file is classified, in order:

  1. Extension .mjs is an ES module; .cjs is CommonJS; .json, .node and .wasm are their own formats.
  2. --input-type for --eval and standard input code.
  3. Extension .js (and files with no extension): the nearest package.json type.
  4. If that gives no answer (no type, or no package.json), Node.js uses syntax detection: it first parses the file as CommonJS, and if that fails with an error that only ES module syntax explains (a top-level import/export, import.meta, or top-level await), it runs the file as an ES module instead.

Usage notes

  • Always set type explicitly in your own packages. Without it, Node.js must guess and may print a warning that suggests adding the field. It also speeds up loading, since no failed parse is needed.
  • type applies to the package folder, including files in sub-folders, but it does not change how dependencies in node_modules are loaded; each of them has its own package.json.
  • TypeScript also reads it: with "module": "nodenext", .ts files follow the same rule as .js ones, and .mts and .cts correspond to .mjs and .cjs.
  • Mixed code bases: use "type": "module" and rename the CommonJS files to .cjs, or the reverse with .mjs. See File extensions.
  • A mismatch fails loudly. require in an ES module gives ReferenceError: require is not defined in ES module scope; import in a CommonJS file gives SyntaxError: Cannot use import statement outside a module (except where detection rescues it).
  • Detection is a safety net, not a design. A file with both ES and CommonJS syntax cannot run: it fails with an error, as the third file above shows.
  • Other values such as "type": "typescript" do not exist. Type stripping in Node.js 22.18 and newer uses .ts, .mts, .cts extensions and the same type field.
  • Changing type in a published package is a breaking change for everyone who deep-imports its files; consider exports conditions to serve both worlds.