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.
{
"name": "my-app",
"type": "module"
}
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 process.stdin), 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 process.stdin), it gets the next line from this box.
Syntax
"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:
- Extension
.mjsis an ES module;.cjsis CommonJS;.json,.nodeand.wasmare their own formats. --input-typefor--evaland standard input code.- Extension
.js(and files with no extension): the nearestpackage.jsontype. - If that gives no answer (no
type, or nopackage.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-levelimport/export,import.meta, or top-levelawait), it runs the file as an ES module instead.
Usage notes
- Always set
typeexplicitly 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. typeapplies to the package folder, including files in sub-folders, but it does not change how dependencies innode_modulesare loaded; each of them has its ownpackage.json.- TypeScript also reads it: with
"module": "nodenext",.tsfiles follow the same rule as.jsones, and.mtsand.ctscorrespond to.mjsand.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.
requirein an ES module givesReferenceError: require is not defined in ES module scope;importin a CommonJS file givesSyntaxError: 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,.ctsextensions and the sametypefield. - Changing
typein a published package is a breaking change for everyone who deep-imports its files; considerexportsconditions to serve both worlds.