ES modules versus CommonJS in Node.js

What it is

CommonJS (CJS) is Node's original module system: require() loads synchronously at run time and a module exports whatever it assigns to module.exports. ES modules (ESM) are the language standard: import and export are static, resolved before the module body runs, loading is asynchronous, top-level await is allowed, and import.meta carries module metadata. Node decides per file: .mjs is always ESM, .cjs always CJS, and .js follows the nearest package.json "type" field. Without a "type" field the packages documentation calls the file ambiguous: current Node versions run it as CommonJS first and, if the parser finds ES module syntax, re-evaluate it as an ES module (syntax detection); older versions simply treat it as CommonJS. The ESM documentation lists what is missing in ESM (require, module.exports, __filename, __dirname) and the replacements: import.meta.filename, import.meta.dirname, import.meta.resolve() and module.createRequire(). ESM can import CommonJS (the default import is module.exports), and current Node versions can require() an ES module as long as its graph contains no top-level await.

Why it matters

Mixing the two systems is behind the most common start-up errors in Node projects: "Cannot use import statement outside a module", ERR_REQUIRE_ESM, exports is not defined. Test runners, TypeScript output and bundlers each have their own module setting, and a mismatch fails at run time rather than at build time.

How to apply

• New code: set "type": "module" in package.json and write ESM throughout; name the few files that must stay CommonJS .cjs.
• Relative imports in ESM must include the file extension (./util.js, ./dir/index.js); the resolver does not guess.
• JSON is imported with an attribute: import cfg from "./cfg.json" with { type: "json" }.
• Libraries shipping both formats: declare "exports" with import and require conditions, and read the packages documentation and its linked examples repository on dual packages before doing so; a package loaded through both entry points exists twice, with separate module state (the dual package hazard).
• In browsers, module scripts must be served with a JavaScript MIME type such as text/javascript; MDN documents the strict MIME type checking error for .mjs files served otherwise.

Pitfalls

Circular imports behave differently: ESM bindings are live but may be uninitialised when read early. require() of an ESM that uses top-level await throws ERR_REQUIRE_ASYNC_MODULE; use import() instead. A compiler that emits require calls into a "type": "module" package produces code that fails on load; keep the compiler's module output setting aligned with the runtime.