fix(@angular/build): correct misleading error message for top-level await#32887
fix(@angular/build): correct misleading error message for top-level await#32887maruthang wants to merge 5 commits into
Conversation
Sorry, something went wrong.
…wait When using top-level await in a Zone.js application, esbuild would show an error mentioning "target environment" with browser versions, which is misleading. The actual reason is that async/await is downleveled for Zone.js compatibility and top-level await cannot be downleveled. This change augments the esbuild error with a note explaining that top-level await is not supported in applications that use Zone.js, and provides a link to the zoneless Angular documentation. Fixes angular#28904
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request enhances the Angular build process by providing a more descriptive error message when top-level await is used in applications that still utilize Zone.js. The build logic now intercepts specific esbuild errors to add helpful notes and documentation links, and new behavior tests have been added to verify these changes. A review comment suggests extracting the hardcoded error string into a constant to improve maintainability.
Sorry, something went wrong.
…g into named constant
…ithout Zone.js The test incorrectly assumed that top-level await would succeed without Zone.js, but esbuild may still reject it based on the target browser environment. The test now correctly verifies that the Zone.js-specific error message is absent.
… error - Use `??=` and `.push()` instead of spread for notes - Merge two separate notes into a single note with newline - Use `expect(result?.success).toBeTrue()` and `not.toContain` in test
|
Hi @alan-agius4, thank you for the review feedback! I've addressed both suggestions in the latest commit:
Please let me know if there's anything else you'd like me to adjust. |
Sorry, something went wrong.
alan-agius4
added
target: patch
This PR is targeted for the next patch release
action: merge
The PR is ready for merge by the caretaker
action: cleanup
The PR is in need of cleanup, either due to needing a rebase or in response to comments from reviews
and removed
action: merge
The PR is ready for merge by the caretaker
labels
Apr 28, 2026
Reviewers
+1 more reviewer
2 participants
PR Checklist
PR Type
What is the current behavior?
When using top-level
awaitin an Angular app with Zone.js, esbuild reports "Top-level await is not available in the configured target environment" with a list of browser versions. This is misleading — all modern browsers support top-level await. The real issue is that Angular disables native async/await when Zone.js is in use (since Zone.js can't intercept it), and top-level await can't be downleveled.Closes #28904
What is the new behavior?
When the top-level await error occurs and Zone.js is active, the error is augmented with explanatory notes:
Does this PR introduce a breaking change?