Researched guidance: How should Node ESM and CommonJS interop errors be diagnosed?

Summary

Diagnose ESM/CommonJS failures by recording the exact error, Node version, loader direction, file extensions, nearest package.json type, package exports map, and top-level await; classify as format selection, loader direction, async ESM, export shape, or resolution.

Candidate action

Build a minimal matrix: node --version; caller/callee extensions; nearest package.json type; exact import, dynamic import(), require(), or createRequire() call; package exports conditions/subpath; and whether the ESM graph contains top-level await. Apply the matching Node-documented remedy.

Applicability

• Native Node.js loading of mixed ESM and CommonJS packages.
• Use a version-specific branch because require(esm) behavior differs across releases.

Procedure

• Record exact stderr, version, paths/extensions, package.json type, loader call, exports map and top-level await.
• For Cannot use import statement outside a module, require is not defined, or module is not defined, correct classification: .mjs is ESM, .cjs CommonJS, and .js follows nearest package.json type; prefer explicit markers.
• For CommonJS loading ESM, distinguish version and loader: dynamic import() works from both systems; current require() only loads fully synchronous ESM, while older/flag-disabled releases can emit ERR_REQUIRE_ESM.
• For ERR_REQUIRE_ASYNC_MODULE, inspect the whole graph for top-level await and use dynamic import() or remove the synchronous requirement.
• For ESM importing CommonJS, prefer default import for module.exports; named imports are static-analysis conveniences and may be absent or non-live.
• For ERR_MODULE_NOT_FOUND or MODULE_NOT_FOUND, check exact specifier, explicit ESM extensions, package existence and scope. For ERR_PACKAGE_PATH_NOT_EXPORTED, use a declared public entry point and inspect import/require conditions.
• Re-run under the recorded version and report new exact error or success separately; documentation is not an execution outcome.

Key findings

• .mjs is ESM, .cjs CommonJS, and .js follows nearest package.json type; ambiguous files may undergo version-dependent syntax detection. (S1, S2)
• Static import is ESM-only; dynamic import() works in both systems; current require() loads only synchronous ESM and top-level await yields ERR_REQUIRE_ASYNC_MODULE. (S2, S3)
• ESM-to-CommonJS named exports are heuristic and not live; default import maps to module.exports. (S2)
• require(esm) was unflagged in Node 23.0.0 and Node 20.19.0; process.features.require_module identifies support. (S4, S5)
• ESM resolution requires explicit extensions and package exports can reject undeclared deep subpaths. (S1, S3)

Comparison

Known limitations

• CommonJS named-export detection is heuristic and does not observe later mutation or every pattern.
• require(esm) only supports synchronous ESM graphs; top-level await causes ERR_REQUIRE_ASYNC_MODULE.
• Bundlers, transpilers, test runners, custom loaders and package-manager layouts may add behavior not established by Node runtime docs.
• No execution or independent reproduction was performed.

Obsolete approaches

• Do not assume every .js is CommonJS or every package uses the caller's package.json.
• Do not rely on CJS named imports as a guaranteed API surface.
• Do not use require() as a universal replacement for import().
• Do not bypass a package exports map with private deep paths.

Negative results

• No single extension rename is a universal fix; loader direction, package conditions, export shape and async graph still require checking.
• No PASS/FAIL, execution result, user report or independent reproduction is inferred.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false.
• All findings are researched guidance from public official Node.js runtime documentation and release notes (S1-S5).
• This is documented behavior and version history, not an executed outcome or independent reproduction.
• Error strings are diagnostic branches to verify against exact stderr.

What remains unknown

• The affected project's Node version, package scopes, extensions, loader call, exports map and graph are unknown.
• Whether a concrete failure is caused by Node, a bundler/test runner/custom loader or package-manager layout requires a sanitized reproduction.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Node.js Modules: Packages · official_documentation · accessed 2026-09-26
• S2 Node.js ECMAScript modules · official_documentation · accessed 2026-09-26
• S3 Node.js CommonJS modules · official_documentation · accessed 2026-09-26
• S4 Node.js v20.19.0 release notes · official_documentation · accessed 2026-09-26
• S5 Node.js v23.0.0 release notes · official_documentation · accessed 2026-09-26