ESM default via package.json type module in mixed CommonJS application

Answer first

To keep existing CommonJS consumers working while adding ESM, do not change the root package.json "type" to "module" until the legacy CommonJS files are isolated. The safest incremental boundary is:

• Keep root package.json "type": "commonjs" and write new ESM files as .mjs. .mjs is always ESM regardless of type, and existing require('./file.js') paths stay CommonJS.
• Alternative if you must set root "type": "module": rename every existing CommonJS file that is required by old code to .cjs, or move that legacy code under a subfolder with its own package.json { "type": "commonjs" }. New ESM files can then be .js.

ESM static linking changes circular dependencies. Previously tolerated CommonJS cycles where require returned a partially built module.exports will often surface as undefined bindings or ReferenceError in ESM because imports are live bindings resolved before module execution.

Path globals in ESM are reconstructed per module with import.meta.url. That reconstruction is module-local and does not affect CommonJS resolution.

Confirmed facts

• Module type is determined by the nearest package.json "type" field and file extension. .mjs is always ESM, .cjs is always CJS.
• ESM can import CommonJS. CommonJS cannot synchronously require ESM. CJS must use dynamic import() to load ESM.
• ESM has no __dirname or __filename. The documented reconstruction is:

  import { fileURLToPath } from 'node:url';
  import { dirname } from 'node:path';
  const __filename = fileURLToPath(import.meta.url);
  const __dirname = dirname(__filename);

  This is ESM-only and module-relative.
• One .js path cannot be both ESM and CJS for the same nearest package.json. Changing root type reclassifies all .js files.

Likely explanation

Circular imports in ESM are evaluated in a defined order with live bindings. Accessing an imported binding before the exporting module has executed its top-level code yields undefined or a temporal dead zone error. CommonJS require executes the module at call time and returns the current value of module.exports, which allowed many cycles to appear to work. The same cycle in ESM is likely to break.

Steps for this case

1. Decide boundary. If you need zero path changes for existing require('./file.js'), keep root type commonjs and use .mjs for new ESM.
2. If you want root type module, first rename legacy entrypoints to .cjs or create a legacy/ subfolder with package.json {"type":"commonjs"}. Update internal require paths to the new extension.
3. Audit circular dependencies. Replace top-level cross references with lazy functions or restructure to remove cycles.
4. Replace __dirname/__filename in new ESM files with the import.meta.url reconstruction above. Do not share those values with CJS modules.
5. Verify:

   node --version
   # ESM path globals
   node new-esm.mjs
   # CJS still loads
   node -e "require('./legacy.cjs')"

One missing diagnostic that changes the recommendation: are the existing CommonJS consumers internal require() calls in your repo, or external packages that import your package by name? If external, a nested package.json type boundary is required and you cannot rely on renaming files alone.