CommonJS vs ESM

CommonJS: synchronous, runtime-resolved, value-copied

CommonJS (CJS) is Node’s original module system. You pull a module in with require(), a plain function that runs while your code executes: it reads the target file from disk, evaluates it, and returns whatever that file assigned to module.exports. Because it is an ordinary function call, you can require() conditionally, inside an if, or build the path at runtime — resolution is dynamic and happens line by line.

// math.cjs
function add(a, b) { return a + b; }
let calls = 0;
module.exports = { add, get calls() { return calls; }, bump() { calls++; } };

// app.cjs
const math = require("./math.cjs");   // synchronous: blocks until math.cjs is evaluated
console.log(math.add(2, 3));          // 5
const { add } = math;                 // value copy — `add` is a snapshot of the binding

Two properties matter. First, require() is synchronous and blocking: the calling line does not continue until the required file has fully run, which is why CJS startup is a depth-first walk of the dependency tree. Second, what you get back is a value copy at the moment of require. If you destructure const { add } = require(...), you captured the reference that existed then; if the module later reassigns module.exports.add, your add does not change. CJS also hands every module two path globals for free — __dirname and __filename — because resolution is local and runtime.

ESM: static, hoisted, asynchronous, with live bindings

ECMAScript Modules (ESM) are the standard. You declare dependencies with import/export statements that are static: they must sit at the top level (not inside an if or a function), so the engine can find every import before any code runs. That up-front analysis is the whole point — it builds the full module graph, hoists imports, and lets bundlers see exactly which exports are used so they can drop the rest (tree-shaking). Loading the graph is asynchronous, which is what unlocks top-level await.

// math.mjs
let calls = 0;
export function add(a, b) { return a + b; }
export function bump() { calls++; }
export function getCalls() { return calls; }

// app.mjs
import { add, bump, getCalls } from "./math.mjs";   // hoisted, resolved before run
import { readFile } from "node:fs/promises";

const config = await readFile("config.json", "utf8"); // top-level await — no async wrapper
console.log(add(2, 3));   // 5
bump();
console.log(getCalls());  // 1 — live binding reflects the update

The exports you import are live bindings, not copies: import { add } is a read-only view onto the exporting module’s variable. If that module mutates the value behind the name, your import sees the new value — and you may never reassign an imported name yourself (add = ... is a TypeError). There is no __dirname; instead you derive paths from import.meta.url (e.g. new URL("./data.json", import.meta.url)).

How Node decides which system a file is

Node does not guess from the contents. It classifies each file as CJS or ESM by an explicit set of signals, in priority order:

• Extension wins outright. .mjs is always ESM; .cjs is always CJS. These override everything else and are the unambiguous escape hatch.
• "type" in the nearest package.json. For a plain .js file, Node walks up to the closest package.json: "type": "module" makes .js files ESM, "type": "commonjs" (or no field) makes them CJS. Flipping that one field reinterprets every .js file in the package — which is exactly why require is not defined appears the moment you add it.
• The "exports" field controls what import "pkg" and require("pkg") resolve to, and via conditional exports can serve a different file to each — the dual-package pattern.

{
  "name": "mylib",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./package.json": "./package.json"
  }
}

The "exports" map is more than dual publishing: it is your package’s public API boundary. Anything not listed in exports is unreachable from outside — consumers can no longer deep-import mylib/src/internal.js, even if the file exists. That encapsulation is a senior reason to define exports deliberately rather than letting the whole directory leak.

The interop seam — where the time bleeds

The two systems do not compose symmetrically, and this asymmetry is the real pain of the migration era:

• ESM can import CJS. import express from "express" works; the CJS module.exports object becomes the ESM default export. Named imports from a CJS module are best-effort: Node statically analyses the CJS source to guess the named exports, but anything assigned dynamically (module.exports[name] = ...) is invisible, so import { Router } from "express" may fail where import express from "express"; const { Router } = express; works.
• CJS cannot synchronously require() an ESM module — historically it threw ERR_REQUIRE_ESM, because loading ESM is async and require is sync. The portable fix is dynamic import(), which returns a promise and works from either system: const mod = await import("./esm-only.mjs"). (Recent Node versions can require() a synchronous ESM graph, but dynamic import() is the rule that always holds.)

// CJS file needing an ESM-only dependency
async function main() {
  const { default: chalk } = await import("chalk"); // chalk is ESM-only now
  console.log(chalk.green("works from CJS via dynamic import()"));
}
main();