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,7 +19,11 @@ import { LOCALE_DATA_BASE_MODULE } from '../../tools/esbuild/i18n-locale-plugin'
 import { extractLicenses } from '../../tools/esbuild/license-extractor';
 import { profileAsync } from '../../tools/esbuild/profiling';
 import { transformSupportedBrowsersToTargets } from '../../tools/esbuild/target';
-import { calculateEstimatedTransferSizes, logBuildStats } from '../../tools/esbuild/utils';
+import {
+  calculateEstimatedTransferSizes,
+  isZonelessApp,
+  logBuildStats,
+} from '../../tools/esbuild/utils';
 import { BudgetCalculatorResult, checkBudgets } from '../../utils/bundle-calculator';
 import { optimizeChunksThreshold } from '../../utils/environment-options';
 import { resolveAssets } from '../../utils/resolve-assets';
@@ -33,6 +37,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,
@@ -170,6 +178,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',
+          ),
+        }),
+      );
+    });
+  });
+});