Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// app.mjs  -> ES module, always
// app.cjs  -> CommonJS, always
// app.js   -> decided by package.json "type", then by syntax detection

Try it

Node.js Same code, different extension

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 How a plain .js file is classified

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 .cjs file 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. CommonJS require tries .js, .json and .node for 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 a MODULE_TYPELESS_PACKAGE_JSON warning on stderr for files outside node_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, .mts and .cts files; it does not transform enum, namespaces or other syntax that needs code generation unless you opt into transform mode. Imports still name the real file, including the .ts extension.
  • Entry point from the command line. node app.mjs and node app.cjs are unambiguous. For code passed with -e or on stdin use --input-type=module or --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 no type field. A stray empty package.json therefore stops the search.
  • Mixed output from build tools. Compilers commonly emit .mjs and .cjs side by side and point to them from conditional exports.