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

When top-level await is used in an application that includes Zone.js,
esbuild reports that top-level await is not available in the configured
target environment even though the actual cause is the async/await
downleveling required for Zone.js support. The error is now augmented
with a note explaining the Zone.js limitation and pointing to the
zoneless guide.

Closes #28904

Author: maruthang

packages/angular/build/src/builders/application/execute-build.ts

@@ -19,6 +19,7 @@ import { extractLicenses } from '../../tools/esbuild/license-extractor';
 import { profileAsync } from '../../tools/esbuild/profiling';
 import {
   calculateEstimatedTransferSizes,
+  isZonelessApp,
   logBuildStats,
   transformSupportedBrowsersToTargets,
 } from '../../tools/esbuild/utils';
@@ -35,6 +36,10 @@ import { inlineI18n, loadActiveTranslations } from './i18n';
 import { NormalizedApplicationBuildOptions } from './options';
 import { createComponentStyleBundler, setupBundlerContexts } from './setup-bundling';
 
+/** The esbuild error text prefix used to detect top-level await errors. */
+const TOP_LEVEL_AWAIT_ERROR_TEXT =
+  'Top-level await is not available in the configured target environment';
+
 // eslint-disable-next-line max-lines-per-function
 export async function executeBuild(
   options: NormalizedApplicationBuildOptions,
@@ -157,6 +162,24 @@ export async function executeBuild(
 
   // Return if the bundling has errors
   if (bundlingResult.errors) {
+    // If Zone.js is used, augment top-level await errors with a more helpful message.
+    // esbuild's default error mentions "target environment" with browser versions, but
+    // the actual reason is that async/await is downleveled for Zone.js compatibility.
+    if (!isZonelessApp(options.polyfills)) {
+      for (const error of bundlingResult.errors) {
+        if (error.text?.startsWith(TOP_LEVEL_AWAIT_ERROR_TEXT)) {
+          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,
+          });
+        }
+      }
+    }
+
     executionResult.addErrors(bundlingResult.errors);
 
     return executionResult;

packages/angular/build/src/builders/application/tests/behavior/top-level-await-error_spec.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { buildApplication } from '../../index';
+import { APPLICATION_BUILDER_INFO, BASE_OPTIONS, describeBuilder } from '../setup';
+
+describeBuilder(buildApplication, APPLICATION_BUILDER_INFO, (harness) => {
+  describe('Behavior: "Top-level await error message"', () => {
+    it('should show a Zone.js-specific error when top-level await is used with Zone.js', async () => {
+      await harness.writeFile(
+        'src/main.ts',
+        `
+        // The export makes this file a module, which is required for top-level await.
+        export const value = await Promise.resolve('test');
+        console.log(value);
+        `,
+      );
+
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        polyfills: ['zone.js'],
+      });
+
+      const { result, logs } = await harness.executeOnce({ outputLogsOnFailure: false });
+      expect(result?.success).toBeFalse();
+      expect(logs).toContain(
+        jasmine.objectContaining({
+          message: jasmine.stringMatching(
+            'Top-level await is not supported in applications that use Zone.js',
+          ),
+        }),
+      );
+    });
+
+    it('should not show a Zone.js-specific error when top-level await is used without Zone.js', async () => {
+      await harness.writeFile(
+        'src/main.ts',
+        `
+        // The export makes this file a module, which is required for top-level await.
+        export const value = await Promise.resolve('test');
+        console.log(value);
+        `,
+      );
+
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        polyfills: [],
+      });
+
+      const { result, logs } = await harness.executeOnce({ outputLogsOnFailure: false });
+      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',
+          ),
+        }),
+      );
+    });
+  });
+});