When a Node.js 24 ES module imports a CommonJS file, what does the resulting namespace contain, and when are its named exports fixed?
answer
- default is always there
- a second key names module.exports
- names guessed from source text
- built before the code runs
- copied once, not live
basics
~20 sNode builds a namespace whose default export is the CommonJS module.exports value, plus a 'module.exports' key with the same value. Extra named exports come from static analysis of the source and are copied once at import, never updated live.
solid answer
~50 sNode's ES module loader wraps a CommonJS file in a namespace that always has `default` pointing at `module.exports`, whatever type it is. Since Node 23, and so in 24, it also carries a `'module.exports'` key with the same value. On top of that, Node runs a heuristic static analysis over the CommonJS source text to guess which properties `module.exports` will have, because the namespace's shape must be known before the CommonJS code is evaluated. The guessed names become named exports whose values are copied off `module.exports` when the import happens, so a later reassignment or a property added at run time is not reflected. Detection handles common forms such as `exports.name = ...` and typical transpiler output, but misses names computed at run time. The reliable form is the default import, then reading properties from it.
go deeper
Remember that importing CommonJS always gives you module.exports as the default export, and that the default import is the form that always works.
Explain the three kinds of namespace entry, why named exports come from static analysis, and why they are copied once instead of tracking module.exports.
Diagnose a missing named export or a stale value at the boundary from first principles, and know which CommonJS export styles analysis can and cannot see.
Set a rule for a mixed codebase: default-import CommonJS dependencies with dynamic exports, and never expose mutable state through CommonJS named exports.
## Two module systems, one import statement In Node.js an **ES module** may `import` a **CommonJS** file. The two do not share a shape: an ES module has a fixed set of named exports known before any code runs, while a CommonJS module exposes a single `module.exports` value that its code can build, replace or mutate at any time. To bridge them, Node's ES module loader constructs a **module namespace object** for the CommonJS file. Knowing what goes into that object explains almost every surprise at the boundary. ## What the namespace contains For a file `cjs.cjs` containing `exports.name = 'exported'`, `import * as m from './cjs.cjs'` gives: ```js // [Module] { // default: { name: 'exported' }, // 'module.exports': { name: 'exported' }, // name: 'exported' // } ``` Three kinds of entry are present: - **`default`** is always the `module.exports` value, of any type: an object, a function, a class or a primitive. `import cjs from './cjs.cjs'` and `import { default as cjs } from './cjs.cjs'` are the same import. - **`'module.exports'`** holds the same value under a string export name. Node 23.0.0 added it, so Node 24 has it. It marks unambiguously that this value *is* the CommonJS export, mirroring the way an ES module can export a `'module.exports'` name to control what `require()` returns. - **Detected named exports**, here `name`, are extra keys Node found by analysing the source. ## How named exports are detected The namespace's list of names has to exist before the CommonJS module is evaluated, so Node cannot simply run the file and read `Object.keys(module.exports)`. Instead it performs a **heuristic static analysis** of the source text. Detection covers: - assignments such as `exports.name = ...` and `module.exports.name = ...`; - reexport patterns, where one module forwards another module's exports; - the output that common build tools and transpilers emit. Node 24.14.0 replaced the bundled analyser (cjs-module-lexer gave way to merve), but the contract stayed the same: a best-effort list. It misses names that only exist at run time, for example properties attached in a loop, or an object returned by a factory call (`module.exports = createApi()`). A missed name is not an error in the CommonJS module; it just never becomes a named export, so `import { parse } from ...` fails at link time while the default import still holds `parse`. ## When the values are fixed Detected named exports are **copied** off `module.exports` when the module is imported, after its code has run: 1. Node evaluates the CommonJS module, which builds `module.exports`. 2. For each detected name, Node copies the current property value onto the namespace. 3. From then on the namespace is frozen in shape and those values are not updated. The docs say it directly: live binding updates or new exports added to `module.exports` are not detected for these named exports. So if the CommonJS module later does `exports.count++`, an importer holding `import { count }` keeps the old number, while `import cjs from ...` followed by `cjs.count` reads the current property, because `default` is the object itself. | Read | Sees later changes? | |---|---| | `import { count } from './c.cjs'` | No, copied at import | | `import * as m` then `m.count` | No, same copied export | | `import c from './c.cjs'` then `c.count` | Yes, reads the live object | ## Practical guidance - Prefer the default import for CommonJS packages whose exports are built dynamically. - Treat named imports of CommonJS as a convenience that holds only for statically recognisable exports. - Do not rely on named imports to observe mutable state; read it from the default export or expose a function. - When a package mixes both builds, which one you get is decided by its package `exports` conditions, a separate subject. ## Diagnosing a boundary surprise When an import of a CommonJS package does not give what you expect, compare the two views of the same module: 1. Log `Object.keys(await import('pkg'))` to see the namespace: `default`, `'module.exports'` and whatever names analysis detected. 2. Build a local `require` with `module.createRequire(import.meta.url)` and log `Object.keys(require('pkg'))` to see what `module.exports` really holds after the code ran. 3. Names present in step 2 but absent in step 1 are exports the static analysis could not see; read them through the default import. 4. If the namespace's `default` is itself an object with its own `default` property, the package was usually compiled from ES module source to CommonJS, and the interop conventions of its build tool apply.
- Why can't Node simply run the CommonJS module first and read its keys to build the named exports?An ES module graph is linked before it is evaluated: every importer's named imports are checked against each dependency's export names during linking. The CommonJS namespace therefore needs its names before the CommonJS code runs, so Node has to guess them from the source text. Values are filled in after evaluation, but the set of names is decided first.
- A CommonJS package ends with module.exports = createApi(). What do ES module importers get?The default export, and the `'module.exports'` key, are the object `createApi()` returned, so `import api from 'pkg'` then `api.parse` works. Static analysis cannot see the properties a function call will produce, so named imports such as `import { parse } from 'pkg'` find no such export and fail at link time.
Like a building directory printed from the floor plan before tenants move in: it lists the offices the plan shows, misses rooms added later and never updates, but the front door (the default export) always leads to the real building.
- Named imports from CommonJS are live bindings that track module.exports.
- Node runs the CommonJS file first and reads Object.keys(module.exports) to find named exports.
- In Node's native ESM, the default import of a CommonJS module is undefined unless it sets exports.default.
- Every property of module.exports is always available as a named import.
- import * as m from a CommonJS file returns module.exports itself.
Assumes Node.js 24; the 'module.exports' key on CommonJS namespaces arrived in v23.0.0, and v24.14.0 swapped the named-export analyser without changing its contract.