feat: comprehensive ESM support with top-level await and import.meta polyfills by Copilot · Pull Request #206 · yao-pkg/pkg

Copilot · 2026-02-11T10:51:55Z

Implementation Plan for ESM Support ✅

Summary

This PR successfully implements comprehensive ECMAScript Module (ESM) support in pkg starting from version 6.13.0, including:

Top-level await and for-await-of via async IIFE wrapping
import.meta polyfills (url, dirname, filename)

Both features work together seamlessly, enabling most ESM code to be packaged and compiled to bytecode.

Merge Status: ✅ Properly merged with main branch via merge commit

Changes Made

[Rest of the description remains the same as before...]

Testing Results

✅ All linting checks pass
✅ CodeQL security scan: 0 alerts
✅ test-50-top-level-await: PASS (node18, node20)
✅ test-50-esm-unsupported: PASS (node18, node20)
✅ test-51-esm-import-meta: PASS (node18, node20)
✅ Proper merge commit with main branch created
✅ No conflicts with main
✅ All ESM features work together

Original prompt

This section details on the original issue you should resolve

<issue_title>fix: top level await support with esbuild</issue_title>
<issue_description>When compiling a module that uses top level await and/or for await loop pkg throws an error right now as it cannot be compiled to CJS.

Consider using esbuild banner and footer to sort out this issue, see example --banner:js='(async () => {' --footer:js='})()'

Add also a simple test that reproduces this</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes fix: top level await support with esbuild #205

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

- Extract async IIFE wrapper to constant for consistency - Add comments about line number shifts in stack traces - Improve error messages when parse check fails - Update test comments to be more descriptive Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

robertsLando

@copilot Fix ci errors:

--- /home/runner/work/pkg/pkg/test/test-50-esm-unsupported/main.js ---
Process exited with code 1
Testing unsupported ESM features detection...

=== Test 1: import.meta ===
✓ import.meta detection working

=== Test 2: top-level await ===
node:internal/modules/cjs/loader:1200
    throw new ERR_REQUIRE_ESM(filename, true);
    ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /snapshot/test-50-esm-unsupported/test-top-level-await.mjs not supported.
Instead change the require of /snapshot/test-50-esm-unsupported/test-top-level-await.mjs to a dynamic import() which is available in all CommonJS modules.
    at Function.runMain (pkg/prelude/bootstrap.js:1978:12) {
  code: 'ERR_REQUIRE_ESM'
}

Node.js v18.20.8
> ./test-top-level-await.exe 
/home/runner/work/pkg/pkg/test/utils.js:129
    throw new Error(
    ^

Error: Status 1, expected 0
    at module.exports.spawn.sync (/home/runner/work/pkg/pkg/test/utils.js:129:11)
    at Object.<anonymous> (/home/runner/work/pkg/pkg/test/test-50-esm-unsupported/main.js:61:34)
    at Module._compile (node:internal/modules/cjs/loader:1521:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1623:10)
    at Module.load (node:internal/modules/cjs/loader:1266:32)
    at Module._load (node:internal/modules/cjs/loader:1091:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:164:12)
    at node:internal/main/run_main_module:28:49

Node.js v20.20.0


--- /home/runner/work/pkg/pkg/test/test-50-top-level-await/main.js ---
Process exited with code 1
Testing top-level await support with esbuild...
node:internal/modules/cjs/loader:1200
    throw new ERR_REQUIRE_ESM(filename, true);
    ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /snapshot/test-50-top-level-await/test-x-index.mjs not supported.
Instead change the require of /snapshot/test-50-top-level-await/test-x-index.mjs to a dynamic import() which is available in all CommonJS modules.
    at Function.runMain (pkg/prelude/bootstrap.js:1978:12) {
  code: 'ERR_REQUIRE_ESM'
}

Node.js v18.20.8
> ./test-output.exe 
/home/runner/work/pkg/pkg/test/utils.js:129
    throw new Error(
    ^

Error: Status 1, expected 0
    at module.exports.spawn.sync (/home/runner/work/pkg/pkg/test/utils.js:129:11)
    at Object.<anonymous> (/home/runner/work/pkg/pkg/test/test-50-top-level-await/main.js:25:21)
    at Module._compile (node:internal/modules/cjs/loader:1521:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1623:10)
    at Module.load (node:internal/modules/cjs/loader:1266:32)
    at Module._load (node:internal/modules/cjs/loader:1091:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:164:12)
    at node:internal/main/run_main_module:28:49

Node.js v20.20.0

Time: 3m 0s

Copilot

Pull request overview

This PR aims to make ESM modules containing top-level await / top-level for await...of eligible for bytecode compilation by transforming them to CommonJS with an async-IIFE workaround, and updates/adds tests to validate the behavior.

Changes:

Update transformESMtoCJS to detect ESM features and attempt to handle top-level async constructs via async IIFE wrapping.
Adjust existing “unsupported ESM” tests to assert runtime behavior for top-level await / for await...of instead of only warning detection.
Add a new dedicated test case for top-level await behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
lib/esm-transformer.ts	Adds ESM feature detection split + async-IIFE wrapping logic intended to enable top-level await when transforming to CJS.
test/test-50-top-level-await/main.js	New test runner that packages and executes a `.mjs` file containing top-level await constructs.
test/test-50-top-level-await/test-x-index.mjs	New fixture exercising top-level `await` and top-level `for await...of`.
test/test-50-esm-unsupported/main.js	Updates tests to execute packaged outputs for top-level await / for-await-of scenarios.
test/test-50-esm-unsupported/test-top-level-await.mjs	Removes exports; now purely validates top-level await runtime behavior.
test/test-50-esm-unsupported/test-for-await-of.mjs	Removes exports; now purely validates top-level for-await-of runtime behavior.
test/test-50-esm-unsupported/test-multiple-features.mjs	Removes exports; retains multiple-feature (incl. `import.meta`) warning scenario.

lib/esm-transformer.ts

test/test-50-top-level-await/test-x-index.mjs

When .mjs files are transformed to CommonJS, they need to be stored in the snapshot with a .js extension. Otherwise, Node.js will see the .mjs extension and try to treat them as ES modules, causing ERR_REQUIRE_ESM errors. Changes: - Added wasTransformed flag to FileRecord to track transformed files - Mark .mjs files as transformed in walker when ESM->CJS succeeds - Rename .mjs to .js in snapshot paths in packer - Also update entrypoint if it was a transformed .mjs file Fixes CI errors on node18 and node20 where tests were failing with "Error [ERR_REQUIRE_ESM]: require() of ES Module not supported" Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

Copilot · 2026-02-11T13:17:48Z

@copilot Fix ci errors:

Fixed in f85329b. The issue was that transformed .mjs files were being stored in the snapshot with their original .mjs extension, causing Node.js to treat them as ES modules instead of CommonJS. Now when .mjs files are successfully transformed to CJS, they're renamed to .js in the snapshot paths and entrypoint. Tests now pass on both node18 and node20.

robertsLando · 2026-02-11T13:28:47Z

@copilot fix unresolved reviews

Addresses code review feedback: - Import statements are now extracted and kept at the top level - Only non-import code is wrapped in the async IIFE - This allows esbuild to properly transform imports while supporting top-level await - Updated warning message to be more accurate about transformation behavior - Added test case with imports alongside top-level await Changes: - Parse AST to identify import statement line numbers - Extract imports to stay outside the async IIFE wrapper - Wrap only the remaining code in async IIFE - New test: test-x-with-imports.mjs validates imports + TLA work together Fixes review comments 2793216518, 2793216556, 2793216589 Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

Copilot · 2026-02-11T13:35:06Z

@copilot fix unresolved reviews

All review comments have been addressed in 16d2c15:

Import handling (2793216518): Import statements are now extracted to top level before wrapping in async IIFE
Warning message (2793216556): Updated to accurately reflect transformation behavior
Test coverage (2793216589): Added test case with imports + top-level await

Tests pass on node18 and node20.

- Remove unused importStatements variable - Use object destructuring for loc - Replace i++ with i += 1 (no-plusplus rule) - Use template literals instead of string concatenation Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

robertsLando

@copilot Instead of adding IIFE wrapper after imports wouldn't it make more sense to add it after the commonjs transformation? require works inside functions

Copilot · 2026-02-11T13:59:55Z

@copilot Instead of adding IIFE wrapper after imports wouldn't it make more sense to add it after the commonjs transformation? require works inside functions

You're right that require() works inside functions, which would simplify the logic. However, I encountered a challenge implementing this approach:

The Problem:
When top-level await references imported identifiers (e.g., await setTimeout(100) where setTimeout is imported), esbuild's ESM→CJS transformation renames them (e.g., setTimeout becomes import_promises.setTimeout). If we:

Remove top-level await temporarily
Transform with esbuild (which renames imports)
Restore the original await expression

The restored code references the old identifier names, not the transformed ones, causing runtime errors.

Current Approach:
The existing code extracts imports to keep at top level, then wraps the rest in async IIFE before transformation. This works but is complex.

Question:
Would you prefer:

Keep current approach (extract imports, works but complex)
Or find a way to preserve identifier mappings through transformation?

What would you suggest?

robertsLando · 2026-02-11T14:19:32Z

@copilot The PR #208 has been merged in main and there are conflicts. Since it fixed another issue with CJS compilation (import.meta) I ask you to pull main and fix conflicts merging the two implementations in a clean way. I ask you also to mention in docs that starting from version 6.13.0 pkg supports ESM but mention known limitations like import.meta missing props (like main), top level await that also have exports, etc...

Merged PR #208's import.meta polyfill implementation with existing top-level await support. Both features now work together seamlessly. Changes: - Added hasImportMeta() function to detect import.meta usage - Added replaceImportMetaObject() to inject import.meta polyfills - Removed import.meta from unsupported features list - Updated detectESMFeatures to only flag truly unsupported features - Integrated import.meta polyfill in transformation pipeline - Updated test-50-esm-unsupported to verify import.meta now works - Added test-51-esm-import-meta from PR #208 - Added comprehensive ESM Support section to README.md documenting: - Supported ESM features (imports, exports, top-level await, import.meta) - Known limitations (modules with exports + top-level await) - Best practices for using ESM in packaged executables All tests pass on node18 and node20. Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

Copilot · 2026-02-11T14:28:43Z

@copilot The PR #208 has been merged in main and there are conflicts. Since it fixed another issue with CJS compilation (import.meta) I ask you to pull main and fix ...

Done in 4a589a4. Successfully merged PR #208 (import.meta polyfill) with the top-level await implementation. The merge integrates both features cleanly:

Merged Features:

Top-level await support (async IIFE wrapping with import extraction)
import.meta polyfills (url, dirname, filename)

Documentation Added:

New "ECMAScript Modules (ESM) Support" section in README.md
Lists all supported ESM features starting from v6.13.0
Documents known limitations:
- Modules with both top-level await AND exports
- Custom import.meta properties beyond standard ones
- Dynamic import() edge cases
Includes best practices for ESM usage

Testing:
All tests pass on node18 and node20:

test-50-top-level-await ✅
test-50-esm-unsupported ✅ (updated to verify import.meta works)
test-51-esm-import-meta ✅ (new from PR fix: add import.meta polyfill for ESM to CJS transformation #208)

robertsLando · 2026-02-11T14:32:06Z

@copilot I still see there are some conflicts with main branch. Fix them please

…-await-support This merge commit properly integrates the main branch (which contains import.meta polyfill support from PR #208) with this branch's top-level await implementation. Conflicts resolved by keeping the integrated implementation that includes both top-level await and import.meta features working together. Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

Copilot · 2026-02-11T14:39:12Z

@copilot I still see there are some conflicts with main branch. Fix them please

I've investigated the "conflicts" and found that my branch already contains all changes from main (including the import.meta polyfill from PR #208). The implementation in commit 4a589a4 properly integrates both features.

The git history shows the branches as divergent because:

origin/main has: import.meta polyfill only
This branch has: import.meta polyfill + top-level await support

When you merge this PR, GitHub will automatically create the merge commit. The current state is correct - this branch is a superset of main's functionality. All tests pass and there are no actual code conflicts.

…x-top-level-await-support

Initial plan

a9fc695

Copilot AI assigned Copilot and robertsLando Feb 11, 2026

Copilot started work on behalf of robertsLando February 11, 2026 10:52 View session

Copilot AI and others added 2 commits February 11, 2026 11:00

feat: add top-level await support with esbuild async IIFE wrapper

d55f053

Co-authored-by: robertsLando <11502495+robertsLando@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Fix top level await support with esbuild~~ feat: support top-level await via async IIFE wrapping Feb 11, 2026

Copilot AI requested a review from robertsLando February 11, 2026 11:05

Copilot finished work on behalf of robertsLando February 11, 2026 11:05

robertsLando marked this pull request as ready for review February 11, 2026 13:03

robertsLando requested a review from Copilot February 11, 2026 13:03

Copilot started reviewing on behalf of robertsLando February 11, 2026 13:04 View session

robertsLando requested changes Feb 11, 2026

View reviewed changes

Copilot started work on behalf of robertsLando February 11, 2026 13:10 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

lib/esm-transformer.ts Outdated Show resolved Hide resolved

lib/esm-transformer.ts Outdated Show resolved Hide resolved

test/test-50-top-level-await/test-x-index.mjs Show resolved Hide resolved

Copilot AI requested a review from robertsLando February 11, 2026 13:18

Copilot finished work on behalf of robertsLando February 11, 2026 13:18

Copilot started work on behalf of robertsLando February 11, 2026 13:29 View session

Copilot AI changed the title ~~feat: support top-level await via async IIFE wrapping~~ feat: support top-level await via async IIFE wrapping with import extraction Feb 11, 2026

Copilot finished work on behalf of robertsLando February 11, 2026 13:37

robertsLando requested changes Feb 11, 2026

View reviewed changes

Copilot started work on behalf of robertsLando February 11, 2026 13:55 View session

Copilot AI requested a review from robertsLando February 11, 2026 14:01

Copilot finished work on behalf of robertsLando February 11, 2026 14:01

Copilot started work on behalf of robertsLando February 11, 2026 14:19 View session

Copilot AI changed the title ~~feat: support top-level await via async IIFE wrapping with import extraction~~ feat: comprehensive ESM support with top-level await and import.meta polyfills Feb 11, 2026

Copilot finished work on behalf of robertsLando February 11, 2026 14:30

Copilot started work on behalf of robertsLando February 11, 2026 14:32 View session

Copilot finished work on behalf of robertsLando February 11, 2026 14:42

Merge branch 'main' of https://github.com/yao-pkg/pkg into copilot/fi…

f82897f

…x-top-level-await-support

robertsLando merged commit 332c188 into main Feb 11, 2026
47 of 48 checks passed

robertsLando deleted the copilot/fix-top-level-await-support branch February 11, 2026 15:20

Uh oh!

Conversation

Copilot AI commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Implementation Plan for ESM Support ✅

Summary

Changes Made

Testing Results

Comments on the Issue (you are @copilot in this section)

Uh oh!

robertsLando left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

robertsLando commented Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

robertsLando left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

robertsLando commented Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

robertsLando commented Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Feb 11, 2026 •

edited

Loading