CommonJS vs ESM in Node.js

languages/javascript/16-modules already covers ES modules in depth — named/default exports, live bindings, the two-phase linking/evaluation model. This topic assumes that content and does not repeat it. Instead it covers CommonJS's own mechanism in depth (Node's original module system, still the default for plain .js files), then the real interop problems that come from having two module systems in one runtime.

1The Basic Contrast

// CommonJS — math.js
const PI = 3.14159;
function square(x) { return x * x; }
module.exports = { PI, square };

// CommonJS — app.js
const { PI, square } = require("./math.js");

// ESM — math.mjs (covered in languages/javascript/16-modules)
export const PI = 3.14159;
export function square(x) { return x * x; }

2require()'s Resolution Algorithm

require("some-specifier") doesn't just "find a file" — it runs a specific, ordered algorithm:

require("X") from module at path Y:

1. If X is a core module ("fs", "path", "http", ...) → return it, done.
2. If X starts with "/", "./", or "../" → resolve as a file/directory:
     a. try X, X.js, X.json, X.node (exact extensions)
     b. if X is a directory: look at X/package.json "main" field, else X/index.js
3. Otherwise (a bare specifier like "lodash") → walk node_modules:
     a. look in Y/node_modules/X
     b. if not found, go to the PARENT directory's node_modules
     c. repeat, walking UP the directory tree, until found or reaching the filesystem root

/project/src/deep/nested/file.js  →  require("lodash")
  checks: /project/src/deep/nested/node_modules/lodash
          /project/src/deep/node_modules/lodash
          /project/src/node_modules/lodash
          /project/node_modules/lodash        ← found here, stop walking

For package imports, Node also checks the target package's own package.json for a "main" field (legacy) or the more specific "exports" field (modern, can restrict/remap what's importable — see section 5) to determine which actual file require("lodash") resolves to.

3The Require Cache — Modules Are Singletons Per Absolute Path

// counter.js
let count = 0;
module.exports = { increment: () => ++count, get: () => count };

// a.js
const counter = require("./counter.js");
counter.increment();

// b.js
const counter = require("./counter.js"); // SAME object as a.js got — not re-executed
console.log(counter.get()); // sees a.js's increment, because it's the identical cached instance

The first time a file is require()d, Node executes it and stores the resulting module.exports in require.cache, keyed by the file's fully resolved absolute path. Every subsequent require() of that same resolved path — from anywhere in the program — returns the cached object directly, without re-running the file. This is why requiring the same module twice gives you the same object reference, not a fresh copy, and it's the mechanism that makes singletons like the counter.js example above work naturally.

console.log(require.cache); // inspect what's currently cached, keyed by absolute path
delete require.cache[require.resolve("./counter.js")]; // force a fresh re-require (rarely a good idea)

4Circular require() — What Each Side Actually Sees

Because require() is synchronous and cache-based, a circular dependency doesn't deadlock — it returns whatever the partially-completed module.exports looks like at the moment of the circular call.

// a.js
console.log("a starting");
exports.done = false;
const b = require("./b.js");
console.log("in a, b.done =", b.done);
exports.done = true;

// b.js
console.log("b starting");
exports.done = false;
const a = require("./a.js"); // a.js is ALREADY in the require cache, mid-execution
console.log("in b, a.done =", a.done); // sees a's EXPORTS OBJECT AS IT EXISTED AT THIS MOMENT
exports.done = true;

// main.js
require("./a.js");

Trace: main requires a → a starts, sets exports.done = false, then requires b → b starts, sets its own exports.done = false, then requires a again. Because a.js is already present in require.cache (marked as "in progress," with whatever partial exports it had built so far), require("./a.js") inside b.js does not re-run a.js — it immediately returns a's current, still-incomplete exports object, where done is false. b finishes, sets its own done = true, control returns to a, which finishes and sets its done = true. Any code holding onto that early reference to a's exports (like b did) sees the partial snapshot from that early point — it will NOT retroactively see a.done flip to true unless it re-reads a live property off the same object reference after a finishes (property lookups on the shared object do reflect later mutations; it's specifically the timing of when you read it that matters).

5Module Wrapping — Why require, module, __dirname "Look Like" Globals

// what you write:
console.log(__dirname);
module.exports = { hello: () => "hi" };

// what Node actually runs — every CommonJS file is wrapped in a function:
(function (exports, require, module, __filename, __dirname) {
  console.log(__dirname);
  module.exports = { hello: () => "hi" };
});

Node wraps every CommonJS file's contents in this function before executing it, then calls that function with the module's real exports, a require bound to that file's directory (for resolving relative paths), the module object itself, and the computed __filename/__dirname. This is why those identifiers are available without any import/declaration — they're just function parameters, scoped to that one file, not actual global variables. It also explains why top-level var/function declarations in a CommonJS file don't leak onto the real global object — they're scoped inside this wrapper function.

// cjs-module.cjs
module.exports = { greet: () => "hi" };

// esm-consumer.mjs
import cjsModule from "./cjs-module.cjs"; // module.exports AS A WHOLE becomes the default export
cjsModule.greet();

import { greet } from "./cjs-module.cjs"; // ALSO often works — Node tries to synthesize named exports

// this throws — ERR_REQUIRE_ESM
const esmModule = require("./real-esm-module.mjs");

// the correct way: dynamic import, which is always async
import("./real-esm-module.mjs").then((mod) => mod.doThing());

{
  "name": "my-package",
  "exports": {
    ".": {
      "require": "./dist/index.cjs",
      "import": "./dist/index.mjs"
    }
  }
}

⚠️ Common Pitfalls

1. Assuming require.cache guarantees fresh state per test run — long-running processes (like test suites) can leak stale cached modules between logically separate test cases if you mutate shared module state.
2. Expecting a circular require() to see the "final" version of the other module — it sees exactly the partial exports object as it existed at the moment of the circular call (section 4); restructure to avoid circular dependencies where the order actually matters.
3. Named-importing from a CommonJS module and getting undefined — cjs-module-lexer's static analysis can miss dynamically-assigned exports; falling back to the default import (import cjs from "./x.cjs") and destructuring at runtime is more reliable for tricky CJS modules.
4. Trying to require() a package that ships only ESM — increasingly common for modern packages; the fix is dynamic import(), not require(), and it changes your calling code from sync to async.
5. Forgetting "type": "module" changes ALL plain .js files in that package, not just the entry point — a lone leftover CommonJS-style .js file in a "type": "module" package will fail to parse.

📋 Quick Reference

require("core")            → step 1, no filesystem lookup
require("./x")/require("../x") → resolve relative to caller's directory
require("bare-name")        → walk node_modules UP the directory tree
require.cache               → keyed by resolved absolute path, singleton per path
circular require            → returns the OTHER module's partial exports at that moment
module wrapper               → (exports, require, module, __filename, __dirname) => {...}
import cjsFile.cjs           → module.exports becomes default export; named exports best-effort (cjs-module-lexer)
require(esmFile.mjs)          → ERR_REQUIRE_ESM — use dynamic import() instead
"type": "module"             → .js files in that package are ESM; use .cjs for CommonJS there
"exports" field               → per-package require/import build selection (dual packages)

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: node_commonjs_vs_esm_theory.md · generated by tools/build_lessons.py