skip to content

You lead a large CommonJS Node.js 24 service that now depends on one ESM-only and one CommonJS-only package; how do you decide whether, and how, to move it to ESM?

level: principalimportance: should knowfreq 30%

answer

  1. require(esm) removed the forcing function
  2. staying CommonJS is a real option
  3. the cost sits in tests and tooling
  4. flip type once, rename the leftovers
  5. default-import the CommonJS-only package

basics

~20 s

In Node 24, require() loads synchronous ES modules, so an ESM-only dependency without top-level await no longer forces a migration. Decide on cost: tests, mocks and require-patching tools, against what ESM buys, such as top-level await.

solid answer

~50 s

First, separate the dependency problem from the migration. In Node 24 a CommonJS service can `require()` the ESM-only package as long as its graph has no top-level `await`, and ESM code can always import the CommonJS-only package through its default export, so neither dependency forces a move. Migrate when ESM buys something: top-level `await` at startup, alignment with where the ecosystem is going, or one format for the team. The cost is rarely the syntax; it is tests and mocks that clear `require.cache`, tooling that patches `require`, `__dirname` paths, JSON loads and relative specifiers needing extensions. If you go, flip `"type": "module"` once per package and rename the files that must stay CommonJS to `.cjs`, rather than leaving an indefinite `.mjs` patchwork. If you stay, inventory the ESM edges with `--trace-require-module` and pin the ESM-only package.

go deeper

for a junior

Know that Node 24 lets CommonJS require() synchronous ES modules and ES modules import CommonJS, so mixed services work.

for a middle

List what changes when a package flips to "type": "module": .cjs renames, import.meta paths, file extensions, JSON import attributes.

for a senior

Identify where a migration really hurts, require.cache-based tests and require-patching tools, and how to guard a require()d ESM dependency.

for a principal

Make the call on value and cost: stay with guard rails, flip once per package, or stage with a deadline, and say what would change your mind.

## The decision changed with Node 24 Until recently an **ESM-only** dependency forced a CommonJS service's hand: `require()` failed, so either the service moved to ES modules or every call site switched to asynchronous `import()`. In Node 24, `require()` loads **synchronous** ES modules without a flag, and the feature is marked stable from 24.15.0. Combined with the long-standing ability of ES modules to import CommonJS, both directions now work inside one process. That turns "must we migrate?" into a genuine choice with costs on each side. ## Option A: stay on CommonJS Keep the service in CommonJS and consume the ESM-only package with `require()`. - **Gains:** no code churn; existing tests, mocks and tooling keep working. - **Costs:** the dependency's graph must stay free of top-level `await`. If a release adds one anywhere in that graph, `require()` throws `ERR_REQUIRE_ASYNC_MODULE` and the call site has to become `await import()`. - **Guard rails:** pin the package, cover the `require()` edge with a test, and run `--trace-require-module=no-node-modules` to list every place the code requires ESM. ## Option B: move the service to ESM Set `"type": "module"` and convert. What breaks is predictable: 1. Every `.js` file becomes an ES module at once; files that must stay CommonJS (a config file read by a tool, a script) get renamed to `.cjs`. 2. `__dirname` and `__filename` become `import.meta.dirname` and `import.meta.filename`. 3. Relative imports need full file extensions, and JSON needs `with { type: 'json' }`. 4. Tests or hot reload that delete `require.cache` entries stop working, because ES modules sit in a separate cache with no public eviction. 5. Tooling that hooks `require` (instrumentation, mocking helpers) must support ES modules, typically through module customization hooks. The CommonJS-only package keeps working: a default import gives its `module.exports`, and named imports work where Node's static analysis detects them. `module.createRequire(import.meta.url)` remains the escape hatch for native addons. ## Option C: a staged migration Large services rarely flip in one change. Two staging patterns are workable: - **Leaves first, as `.mjs`.** Convert modules with no internal dependants. CommonJS callers can `require()` them while they stay free of top-level `await`. - **Package by package.** In a repository with several packages, flip `"type"` one package at a time. Staging needs an end date. A codebase left half `.mjs` and half `.js` for years doubles the rules every engineer has to hold. ## The two dependencies, concretely Whichever option you pick, each dependency has a known bridge: - **The ESM-only package.** From CommonJS, `require()` returns its namespace object, so a default export is read as `.default`. From ES modules it is an ordinary `import`. If its graph uses top-level `await`, only `import()` works, and that alone can tip the decision towards moving. - **The CommonJS-only package.** From ES modules, `import pkg from '...'` always yields its `module.exports`. Named imports work only for exports Node's static analysis can detect, so default-import it if its exports are built at run time. ## A time-boxed plan if you move 1. Inventory: list `require.cache` users, `__dirname` uses, JSON loads, `require`-patching tools and every `.js` file that must stay CommonJS. 2. Fix the tooling first, on CommonJS, so the switch itself is mechanical. 3. Flip `"type": "module"` per package in one change each, renaming the exceptions to `.cjs`. 4. Delete any temporary `createRequire` shims by a fixed date, keeping only the ones for native addons. ## How to decide | Factor | Favours staying | Favours moving | |---|---|---| | Dependencies use top-level await | | yes: require() cannot load them | | Test suite relies on require.cache | yes, until redesigned | | | Startup wants top-level await | | yes | | Instrumentation supports ESM | | required first | | Team bandwidth for churn | low | available | Questions a lead should answer before choosing: - What does ESM concretely buy this service in the next year? - Which tests, mocks and tools break, and who owns fixing them? - Can the team finish the move within a bounded window, or will it stall halfway? - How will the team learn when a `require()`d dependency adds top-level `await`? There is no universal answer. A stable service with heavy CommonJS test tooling can reasonably stay put with guard rails; a service whose dependencies already use top-level `await`, or whose team is starting new packages, gains more from a planned, time-boxed move.

  • If you stay on CommonJS, how do you stop a future dependency release from breaking production through require()?
    Pin the ESM-only package and update it deliberately, with a test that loads it through `require()`. Run `--trace-require-module=no-node-modules` in CI to keep an inventory of every ESM edge, so a new top-level `await` shows up as a failing test rather than an `ERR_REQUIRE_ASYNC_MODULE` at deploy time.
  • During the move, what is the cleanest way to keep a few files as CommonJS?
    Flip `"type": "module"` once and rename only the files that must remain CommonJS to `.cjs`. The extension is an explicit marker that overrides the package's `"type"`, so those files load as CommonJS while everything else is ESM, and the exceptions are visible in the file names.

  • An ESM-only dependency forces a CommonJS service to migrate to ESM in Node 24.
  • Once a service is ESM it can no longer use CommonJS-only packages.
  • Converting the syntax is the main cost; tests and tooling are unaffected.
  • Leaving files as .mjs indefinitely is a free middle ground.
  • require() of an ES module re-evaluates it on each call, so it is unusable at scale.

Assumes Node.js 24, where require() of synchronous ES modules runs without a flag (since v22.12.0) and is no longer experimental from v24.15.0, which is what makes staying on CommonJS viable.