Node.js CommonJS require() and ESM Top-Level Await Interoperability

Answer

Node.js does not expose a public API to pre-detect top-level await (TLA) in an ESM module. If a CommonJS script calls require() on an ESM file whose graph contains TLA, Node.js throws ERR_REQUIRE_ASYNC_MODULE. There is no documented mechanism to supply a synchronous fallback export for that entry point. The practical options are runtime detection with try/catch, custom static parsing, or providing a separate CommonJS wrapper that uses dynamic import().

Detect TLA before calling require()

1. Wrap the require() call in try/catch and inspect err.code. If it equals ERR_REQUIRE_ASYNC_MODULE, the module cannot be loaded synchronously; fall back to import().
2. Read the ESM source file and parse it with a module-aware parser such as @babel/parser using sourceType: 'module'. Inspect ast.program.body for AwaitExpression nodes at the top level. This can produce false positives when await appears inside an immediately invoked async function.

Provide a CommonJS fallback

Node.js does not document a synchronous fallback for an ESM entry that uses TLA. Library authors typically ship a separate .cjs entry that performs import() and re-exports a Promise-based API, or refactor the TLA into an exported async initialization function so CommonJS consumers can call it asynchronously.

Verification

In Node.js v22.12.0 or later, create an ESM file containing top-level await and run node -e "require('./file.mjs')". Confirm that ERR_REQUIRE_ASYNC_MODULE is thrown.

Missing diagnostic detail

Do you control the ESM module source? If yes, refactoring top-level await into an exported async function changes the recommendation from runtime detection to providing a CommonJS wrapper. If no, runtime try/catch or static parsing is the only safe strategy.