Node.js Reference ยท Module Systems
File extensions .mjs, .cjs and .mts in Node.js
How Node.js decides whether a file is an ES module or CommonJS: .mjs, .cjs, .js with package type, .mts and .cts, extensionless entries and detection.
Node.js has two module systems, and every file is loaded as exactly one of them. The file extension is the strongest signal: .mjs is always an ES module and .cjs is always CommonJS. For plain .js files Node looks at the "type" field of the nearest package.json, and if that says nothing it can inspect the source.
TypeScript extensions follow the same rule: .mts is an ES module and .cts is CommonJS, after the types are stripped. Knowing the order of these checks explains most require is not defined and Cannot use import statement errors.
// app.mjs -> ES module, always // app.cjs -> CommonJS, always // app.js -> decided by package.json "type", then by syntax detection
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
The rules are applied in this order; the first one that decides wins.
| Rule | Result |
|---|---|
Extension .mjs or .mts |
ES module |
Extension .cjs or .cts |
CommonJS |
Extension .js or .ts, nearest package.json has "type": "module" |
ES module |
Extension .js or .ts, nearest package.json has "type": "commonjs" |
CommonJS |
Extension .js, no "type" and the source contains import/export or top-level await |
ES module (syntax detection) |
Extension .js, no "type", plain script |
CommonJS |
Extension .json |
JSON (needs with { type: 'json' } when imported) |
Extension .node |
Native addon (CommonJS require only) |
Extension .wasm |
WebAssembly (behind a flag) |
| Extensionless file | Treated like .js and classified by "type" |
Errors: ERR_REQUIRE_ESM / ERR_REQUIRE_ASYNC_MODULE when require() meets an ES module it cannot load, ReferenceError: require is not defined in ES module scope when CommonJS globals are used in an ES module, and SyntaxError: Cannot use import statement outside a module when a CommonJS-classified file uses import.
Usage notes
- The extension beats
package.json. A.cjsfile inside a"type": "module"package is still CommonJS, which is how you keep a config file or a legacy helper next to ES modules. - Always write the extension in ES module imports.
import './util'fails in ES modules;import './util.js'works. CommonJSrequiretries.js,.jsonand.nodefor you. - Syntax detection costs a parse. When there is no
"type"Node may have to try one system and fall back to the other, and it prints aMODULE_TYPELESS_PACKAGE_JSONwarning on stderr for files outsidenode_modules(you can see it under the second example). Libraries and apps should set"type"explicitly. - TypeScript stays out of the way. Node strips types from
.ts,.mtsand.ctsfiles; it does not transformenum, namespaces or other syntax that needs code generation unless you opt into transform mode. Imports still name the real file, including the.tsextension. - Entry point from the command line.
node app.mjsandnode app.cjsare unambiguous. For code passed with-eor on stdin use--input-type=moduleor--input-type=commonjs(read-only, cannot be shown here). - Package scope. The "nearest
package.json" is the first one found walking up from the file, even if it has notypefield. A stray emptypackage.jsontherefore stops the search. - Mixed output from build tools. Compilers commonly emit
.mjsand.cjsside by side and point to them from conditional exports.