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

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

@@ -21,6 +21,7 @@ import { extractLicenses } from '../../tools/esbuild/license-extractor';
 import { profileAsync } from '../../tools/esbuild/profiling';
 import {
   calculateEstimatedTransferSizes,
+  isZonelessApp,
   logBuildStats,
   transformSupportedBrowsersToTargets,
 } from '../../tools/esbuild/utils';
@@ -37,6 +38,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,
@@ -156,6 +161,29 @@ 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 = [
+            {
+              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 ?? []),
+          ];
+        }
+      }
+    }
+
     executionResult.addErrors(bundlingResult.errors);
 
     return executionResult;

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

@@ -0,0 +1,64 @@
+/**
+ * @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',
+        `
+        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',
+        `
+        const value = await Promise.resolve('test');
+        console.log(value);
+        `,
+      );
+
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        polyfills: [],
+      });
+
+      const { result, logs } = await harness.executeOnce({ outputLogsOnFailure: false });
+      // Without Zone.js, the build may still fail due to target environment constraints,
+      // but the error should NOT contain the Zone.js-specific message
+      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();
+    });
+  });
+});