In a CommonJS Node.js 24 service, what does require() return for an ESM-only dependency, and when does it throw ERR_REQUIRE_ASYNC_MODULE instead?
answer
- synchronous, like import() without the promise
- namespace object, default under .default
- a 'module.exports' export overrides
- any top-level await in the graph
- fall back to import()
basics
~20 sNode 24's require() loads a synchronous ES module and returns its module namespace object, with any default export under .default. If the module or anything it imports uses top-level await, require() throws ERR_REQUIRE_ASYNC_MODULE and import() must be used instead.
solid answer
~40 sIn Node 24, `require()` can load an ES module without any flag, and the feature is stable from 24.15.0. It works like `import()` run synchronously: it returns the module namespace object, named exports as properties and the default export under `.default`. When a default export exists Node adds `__esModule: true` so transpiled consumers recognise it, and an ES module can export a value under the string name `'module.exports'` to make `require()` return that value directly. The hard limit is synchrony: if the module, or anything in its import graph, contains top-level `await`, `require()` throws `ERR_REQUIRE_ASYNC_MODULE` and the caller must switch to `await import()`. `--experimental-print-required-tla` prints where those awaits are, `--trace-require-module` lists every require of ESM, and an immediate CommonJS-ESM cycle throws `ERR_REQUIRE_CYCLE_MODULE`.
code
javascript · 15 lines// point.mjs
export default class Point {
constructor(x, y) { this.x = x; this.y = y; }
}
// main.cjs
const ns = require('./point.mjs');
console.log(typeof ns.default); // 'function': the class lives under .default
console.log(ns.__esModule); // true, because a default export exists
try {
require('./uses-tla.mjs'); // contains: await Promise.resolve()
} catch (err) {
console.log(err.code); // 'ERR_REQUIRE_ASYNC_MODULE'
}go deeper
Recall that Node 24 lets CommonJS require() an ES module and that the result is the namespace object, with a default export under .default.
Explain the namespace shape, the __esModule marker, the 'module.exports' export name, and why top-level await makes require() impossible.
Show how you diagnose ERR_REQUIRE_ASYNC_MODULE with --experimental-print-required-tla and why a dependency's new await can break you without an API change.
Weigh relying on require(esm) against moving call sites to import(): it removes async plumbing now but makes a dependency's synchrony part of the contract.
## The old wall and what replaced it For years a **CommonJS** file in Node could not `require()` an **ES module**: it failed with `ERR_REQUIRE_ESM`, and the only bridge was an asynchronous `import()`. That pushed `async` into every call site of an ESM-only dependency. Node removed the wall in stages, and Node 24 is the first LTS line to declare the feature stable, from 24.15.0: | Release | Change | |---|---| | 22.0.0 | `require(esm)` added behind `--experimental-require-module` | | 22.12.0 / 23.0.0 | enabled by default, no flag needed | | 22.13.0 / 23.5.0 | experimental warning no longer printed by default | | 24.15.0 | no longer experimental; the opt-out is `--no-require-module` | `ERR_REQUIRE_ESM` is now deprecated; code can check `process.features.require_module` to know whether the running Node supports the feature. ## What require() returns `require()` loads an ES module when it is marked as one (an `.mjs` file, a `.js` file under `"type": "module"`, or a typeless `.js` file that contains ES module syntax). It then behaves like `import()` run synchronously and returns the **module namespace object** directly: - named exports appear as properties: `require('./distance.mjs').distance`; - a default export appears under `.default`, not as the return value itself; - when the module has a default export, Node adds `__esModule: true` (unless the namespace already defines it), so code emitted by tools that convert ESM to CommonJS treats `.default` correctly. The docs mark this property experimental and say hand-written CommonJS should not depend on it; - if the module exports a value under the string name `'module.exports'` (`export { Point as 'module.exports' }`), `require()` returns that value instead of the namespace, and the module's other named exports are lost to CommonJS callers unless they are attached to that value. The module is loaded through the ES module loader's cache, so it is evaluated once, and later `require()` or `import()` calls of the same URL get the same instance. Reading the result from CommonJS follows from that shape. Destructuring named exports works as usual: `const { distance } = require('./distance.mjs')`. A default export has to be read explicitly, `const Point = require('./point.mjs').default`, unless the module chose a `'module.exports'` export. Code that was written against an older CommonJS build of the same library, where `module.exports` was the class itself, breaks at exactly this point when the library goes ESM-only without a `'module.exports'` export: the call site still runs, but it now holds a namespace object instead of the class, and the first `new` on it throws a `TypeError`. ## The top-level-await limit `require()` is synchronous; a module whose evaluation must wait on a promise cannot finish inside it. So `require()` only accepts a **fully synchronous** graph: 1. If the required module contains top-level `await`, Node throws `ERR_REQUIRE_ASYNC_MODULE`. 2. If *any* module in its import graph contains top-level `await`, the same error is thrown, even when the module you required has none. 3. The message tells you to use `import()` instead. Run with `--experimental-print-required-tla` to have Node print the locations of those awaits; since 24.20.0 the error also carries non-enumerable `requireStack` and `topLevelAwaitLocations` properties. The production consequence is that a dependency can break `require()` callers in a release that adds a top-level `await` deep in its graph, without any change to the API you call. ## Related failure modes and tools - **`ERR_REQUIRE_CYCLE_MODULE`**: a CommonJS-to-ESM or ESM-to-CommonJS edge forms an immediate cycle. Move the `require()` out of top-level code into a function that runs later. - **`--trace-require-module=all`** or **`=no-node-modules`** prints every place a `require()` loads an ES module, which is how you inventory reliance on the feature. - **`--no-require-module`** turns the feature off, restoring the old behaviour where requiring ESM fails. - **Package conditions**: a dual package can still serve a separate CommonJS build to `require()` through its `exports` conditions; that selection is a resolution subject, not this one. ## Choosing between require() and import() - Use `require()` when the dependency is synchronous ESM and the call site must stay synchronous: configuration loading, a plugin registry, legacy modules. - Use `await import()` when the graph has top-level `await`, or when you want to load lazily without blocking. - Pin and test ESM-only dependencies you `require()`, because their graph's synchrony is now part of your contract with them.
- A minor release of an ESM-only dependency suddenly makes require() fail with ERR_REQUIRE_ASYNC_MODULE. How do you find the cause and contain it?Rerun with `--experimental-print-required-tla`, which prints where the top-level awaits sit in the required graph. The fix is either to pin the previous release, or to move that call site to `await import()` and make its caller async. Longer term, `--trace-require-module` gives an inventory of every `require()` of ESM so these edges get tests.
- How can an ES module author make require('./point.mjs') return the Point class itself rather than a namespace?Export it under the string name `'module.exports'`: `export { Point as 'module.exports' }`. `require()` then returns `Point` directly. Other named exports are no longer visible to CommonJS callers, so attach them to `Point`, for example as static properties, if CommonJS code still needs them.
- Node 24 still needs --experimental-require-module to require an ES module.
- require() of an ES module returns a promise you must await.
- require() returns the default export directly instead of the namespace object.
- Only top-level await in the required file itself matters, not in its imports.
- ERR_REQUIRE_ESM is still the error for requiring any ES module in Node 24.
Assumes Node.js 24; require() of ES modules has been unflagged since v22.12.0 and v23.0.0, and Node 24.15.0 marked it no longer experimental.