fix(@angular/build): correct misleading error message for top-level await

[maruthang]

PR Checklist

• The commit message follows our guidelines: https://github.com/angular/angular-cli/blob/main/CONTRIBUTING.md#-commit-message-guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

• Bugfix

What is the current behavior?

When using top-level await in 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:

• "Top-level await is not supported in applications that use Zone.js. Consider removing Zone.js or moving this code into an async function."
• A link to the Angular zoneless documentation at https://angular.dev/guide/zoneless

Does this PR introduce a breaking change?

• Yes
• No

[gemini-code-assist]

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.

[alan-agius4]

Suggested change

	error.notes = [
	{
	text:
	'Top-level await is not supported in applications that use Zone.js. ' +
	'Consider removing Zone.js or moving this code into an async function.',
	location: null,
	},
	{
	text: 'For more information about zoneless Angular applications, visit: https://angular.dev/guide/zoneless',
	location: null,
	},
	...(error.notes ?? []),
	];
	error.notes ??= [];
	error.notes.push(
	{
	text:
	'Top-level await is not supported in applications that use Zone.js. ' +
	'Consider removing Zone.js or moving this code into an async function. \n' + ,
	'For more information about zoneless Angular applications, visit: https://angular.dev/guide/zoneless'
	location: null,
	},
	)

[alan-agius4]

Suggested change

	const zoneJsErrorPresent = logs.some(
	(log) =>
	typeof log.message === 'string' &&
	log.message.includes(
	'Top-level await is not supported in applications that use Zone.js',
	),
	);
	expect(zoneJsErrorPresent).toBeFalse();
	expect(result?.success).toBeTrue();
	expect(logs).not.toContain(
	jasmine.objectContaining({
	level: 'error',
	message: jasmine.stringContaining(`Top-level await is not supported in applications that use Zone.js'`),
	}),
	);

[maruthang]

Hi @alan-agius4, thank you for the review feedback! I've addressed both suggestions in the latest commit:

1. Switched to error.notes ??= [] with .push() and merged the two notes into a single one with a newline separator.
2. Updated the test to use expect(result?.success).toBeTrue() with expect(logs).not.toContain(...) as you suggested.

Please let me know if there's anything else you'd like me to adjust.

[maruthang]

Squashed and rebased onto main: the style: commit type was failing commit-message lint, and the no-Zone.js test needed an export in the generated main.ts (top-level await is only valid in modules, which is why the build failed even without Zone.js). Verified both specs pass locally against the rebased builder.