CJS/ESM interop, deeply: require(esm), named exports, and TLA

require() of ESM — and the top-level-await wall

For years require() of an .mjs (or any ESM) threw ERR_REQUIRE_ESM, and the only bridge from CommonJS to ESM was async dynamic import(). Modern Node (22+, unflagged and stable in 23/24) lifts that: require() can now load an ES module synchronously — but only under one hard condition. The whole ESM graph reachable from the required module must be fully synchronous, i.e. contain no top-level await anywhere. If it does, the loader cannot complete evaluation without yielding to the event loop, and a synchronous require cannot yield — so it throws ERR_REQUIRE_ASYNC_MODULE.

The mechanism: when you require() an ESM module, Node parses and links the graph, and if evaluation is provably synchronous it runs it to completion in the same call and hands you the result. That result is the module namespace object, not a CommonJS module.exports. So default and named exports come back as namespace members:

// config.mjs  — no top-level await: require() succeeds
export const port = 8080;
export default { name: "svc" };

// server.cjs
const ns = require("./config.mjs");
ns.port;        // 8080      ← named export
ns.default;     // { name: "svc" }  ← default lives under .default, NOT ns itself
const { port } = require("./config.mjs"); // also fine

Add one top-level await and the same require throws:

// config.mjs  — top-level await: now an async module
const flags = await loadFlags();   // ← TLA: graph is no longer synchronous
export const port = flags.port;

// server.cjs
const ns = require("./config.mjs");
// ⇒ throws ERR_REQUIRE_ASYNC_MODULE

The tradeoff is sharp and load-bearing: TLA is the feature that makes a module un-require-able. If a library is meant to be consumed by CJS callers via require, top-level await anywhere in its graph is a breaking change — the failure surfaces at the consumer’s boot, not in the library’s tests. The escape hatch when you genuinely need the async module from CJS is to go back to await import("./config.mjs") inside an async function, which can wait for the event loop.

import of CJS — the static lexer that guesses named exports

The reverse direction has its own seam. When ESM does import of a CommonJS module, Node wraps it: the module’s module.exports object becomes the default export. So import pkg from "cjs-dep" always works and pkg is exactly what module.exports was. The subtlety is named imports — import { foo } from "cjs-dep". CommonJS has no static export list, so to support this Node runs cjs-module-lexer, a fast static analyzer, over the source before executing it to guess the names it assigns to exports/module.exports.

Because it is static analysis, it only sees exports it can read syntactically — exports.foo = …, module.exports = { foo }, and a few recognised patterns. Anything assigned dynamically is invisible: a computed key like module.exports[name] = … inside a loop, or Object.assign(exports, computedObject). Those exports exist at runtime, but the lexer never saw their names, so the named import binds to undefined even though the property is right there on the default export.

// plugins.cjs  — exports built dynamically
const names = ["alpha", "beta"];
for (const n of names) module.exports[n] = () => `run ${n}`;

// app.mjs
import { alpha } from "./plugins.cjs"; // alpha is undefined — lexer never saw it
import pkg from "./plugins.cjs";
pkg.alpha;          // ✅ the function — it WAS exported, just not statically visible
const { beta } = pkg; // ✅ robust fallback: default-import, then destructure

The robust rule for consuming any CJS dependency from ESM when named imports misbehave: default-import the whole thing, then destructure (import pkg from "x"; const { foo } = pkg;). That reaches module.exports directly and bypasses the lexer’s static guess entirely.

Transpiler interop: why import express from "express" lies

Most teams never wrote native ESM importing native CJS — they wrote TypeScript or Babel. There, import express from "express" works flawlessly, and that lulls people into thinking native ESM behaves the same. It often does not. Transpiled “ESM” is really CommonJS with an __esModule marker: Babel/TS emit Object.defineProperty(exports, "__esModule", { value: true }) and, under esModuleInterop, wrap each default import in a _interopRequireDefault shim that does module.__esModule ? module : { default: module }. That shim papers over the default-export shape mismatch — a CJS module whose module.exports is a function gets re-homed under .default so import x from finds it.

Native Node ESM has no such shim. It applies the wrapping rule once (module.exports → default) and stops. So code that relied on the transpiler’s interop can break the day you switch "type": "module" and run it natively: a default import that the transpiler reshaped now lands on a differently-shaped object. The lesson: TypeScript’s import ergonomics are a compatibility layer, not Node’s runtime behaviour — verify dependencies under native ESM before assuming parity.

The deeper, API-level cost ties back to the module cache (node unit 01): a package shipped as both CJS and ESM can be loaded as two distinct instances — one through require, one through import — each with its own copy of every variable and class. instanceof fails across the boundary; a singleton initialises twice; a registry populated through one half is empty in the other. Two instances of one package also doubles its memory footprint and bundle weight — a non-trivial RSS cost for a large dependency loaded twice.

ESM has no __dirname, __filename, or require

When you migrate a utility file to ESM and it suddenly breaks on __dirname is not defined, the cause is not a bug — it is a deliberate absence. The last seam is the CommonJS-only globals. In an ESM module __dirname, __filename, and require simply do not exist — they were CJS module-wrapper locals. The replacements are import.meta.url (the module’s own file:// URL) and, when you need to pull in a CJS-only dependency that has no ESM build, module.createRequire(import.meta.url) to mint a working require scoped to the current file:

import { fileURLToPath } from "node:url";
import { dirname } from "node:path";
import { createRequire } from "node:module";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);          // ESM equivalent of __dirname
const require = createRequire(import.meta.url);  // a real require, scoped here
const legacy = require("some-cjs-only-addon");   // pull a CJS dep into ESM, synchronously

Two failure modes round out the picture. First, top-level await serializes startup: a module that awaits at the top blocks every importer until it resolves, and a cycle of TLA modules can deadlock — module A waiting on B’s evaluation while B awaits A’s. TLA is convenient but it makes a module’s evaluation asynchronous, which is precisely what require (above) cannot tolerate and what stretches boot time. Second, conditional require() does not translate to import: a pattern like if (DEBUG) require("./devtools") is impossible with static import, which is hoisted and unconditional — you must use dynamic await import("./devtools") inside the branch, which again introduces async into a place that may have been synchronous.