Skip to content

fix(core): report require() of an ES module with top-level await as ERR_REQUIRE_ASYNC_MODULE - #853

Merged
Brooooooklyn merged 1 commit into
mainfrom
fix/issue-842
Oct 16, 2026
Merged

Brooooooklyn merged 1 commit into
mainfrom
fix/issue-842

Conversation

@Brooooooklyn

Copy link
Copy Markdown
Member

Closes #842

Problem

The pirates hook in register.mjs handles .mjs and .mts, so require() of an ES module is compiled to CommonJS. CommonJS cannot express top-level await, so the transform failed with:

Error: Failed to transform /…/dep.mts: Top-level await is not available in the configured target environment.
  code: 'GenericFailure'

Plain Node.js raises ERR_REQUIRE_ASYNC_MODULE here, and code that catches it to fall back to import() never saw it.

Why not drop .mjs/.mts from pirates

The issue suggests leaving them to Node.js' require(esm), but that only works where the ESM hooks see require(). register.mjs uses the synchronous module.registerHooks() from v26.2.0 only. Below that it uses module.register(), whose hooks never see require(). On Node.js 22 and 24, a require()d .mts would then skip oxc entirely and fall to Node.js' own type stripping. That would lose enums, decorators and tsconfig paths.

Fix

The issue's fallback: report the case with Node.js' error code.

  • Detection: when a CommonJS-target transform fails and the program awaits at its top level, the binding raises Node.js' message instead of the transform error. That means an await, a for await or an await using outside every function, found by a small AST visitor that runs on the failure path only.

    require() cannot be used on an ESM graph with top-level await. Use import() instead.
      Requiring /…/dep.mts
    
  • The code: the binding's errors can only carry napi's GenericFailure status, so the pirates hook recognises that message and sets code: 'ERR_REQUIRE_ASYNC_MODULE'.

  • Which files are ES modules:

    File Treated as Error
    .mts / .mjs ES module ERR_REQUIRE_ASYNC_MODULE
    ambiguous extension, "type": "module" package ES module ERR_REQUIRE_ASYNC_MODULE
    ambiguous extension, package with no type (Node.js' syntax detection runs a file with top-level await as an ES module) ES module ERR_REQUIRE_ASYNC_MODULE
    .cts / .cjs CommonJS transform error, as before
    ambiguous extension, "type": "commonjs" package CommonJS transform error, as before

    Plain Node.js rejects top-level await in a CommonJS file as a SyntaxError instead.

Tests

  • Rust unit test for the top-level await finder.
  • packages/integrate-vitest/__tests__/require-async-module.spec.ts, with all of these require()d from a .cts file:
    • .mts, .mjs, for await, a re-export of an async module, a .ts in a "type": "module" package, and a .ts in a package with no type: all ERR_REQUIRE_ASYNC_MODULE
    • an .mts whose await sits only inside a function still loads
    • the import() fallback works
    • a .ts with top-level await in a "type": "commonjs" package is not reported as ERR_REQUIRE_ASYNC_MODULE

Verification (macOS arm64)

  • Node.js 24.22 and 26.12 give the same codes as plain Node.js for every ES module case above.
  • cargo test --all-features, cargo clippy --all-targets --all-features -- -D warnings, vp run test (219 passed) and vp run lint all pass.

πŸ€– Generated with Claude Code

…RR_REQUIRE_ASYNC_MODULE

The `pirates` hook compiles a `require()`d ES module to CommonJS, which
cannot express top-level await, so the transform failed with a bare
`Failed to transform` GenericFailure. Code that catches Node.js'
ERR_REQUIRE_ASYNC_MODULE to fall back to `import()` never saw it.

When a CommonJS-target transform fails on an ES module that awaits at
its top level (`await`, `for await`, `await using`), the binding now
raises Node.js' message, and the `pirates` hook gives it the
ERR_REQUIRE_ASYNC_MODULE code. A `.cts`/`.cjs` file, or an ambiguous
one in a `"type": "commonjs"` package, is CommonJS whatever its syntax
and keeps the transform error.

Closes #842

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
πŸ“ Code Review βœ… Completed 2026-10-16T12:54:47.031114Z 5e0a7e0 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with πŸ‘€ while any review is running, comments if it has suggestions, and reacts with πŸ‘ once all reviews finish with no findings.

@Brooooooklyn
Brooooooklyn merged commit 4463214 into main Oct 16, 2026
67 checks passed
@Brooooooklyn
Brooooooklyn deleted the fix/issue-842 branch October 16, 2026 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

require() of an ES module with top-level await fails with a transform error instead of ERR_REQUIRE_ASYNC_MODULE

1 participant