feat(@angular/build): expand browser support policy to widely available Baseline

This uses `bl2bl` to generate a `browserslist` configuration from a given widely available Baseline date. The date is hard-coded in `browserslist/package.json`, generating a `.browserslistrc` file at build-time.

Using a browser outside of Angular's minimum defined browser set is still allowed as we expect that _most_ of the time this will work just fine. However, we log a warning to be clear to users that they are outside Angular's supported browserset.

I had to apply a local patch to `bl2bl` as it would unconditionally attempt to write to `package.json` which is read-only in the Bazel file system since it is an input listed in `srcs`. I'll follow up with the maintainers to apply this fix upstream and remove the patch.

I've pinned Angular to the March 31st baseline, but this will likely be updated again as we get closer to the v20 release.

The current set of browsers generated are:

```
Chrome >= 107
ChromeAndroid >= 107
Edge >= 107
Firefox >= 104
FirefoxAndroid >= 104
Safari >= 16
iOS >= 16
```

I opted _not_ to use "downstream browsers". This refers to browsers like Opera, which technically uses Blink and shares the same featureset as Chrome for a particular version. I decided against this to maintain a stricter interpretation of Baseline, given that those browsers are not included in Baseline today. Developers can manually widen their own `.browserslistrc` if they really want to and are comfortable accepting the risks that brings.

Using `bl2bl` as part of the build process means there is a potential risk that a bugfix in `bl2bl` generates a different browserslist file which leads to a different build configuration that causes a problem for existing users. However, it's also just as likely (if not moreso) to fix a problem than cause one, so I'm inclined to call that WAI. If it becomes an issue in the future, we can potentially check in the generated `.browserslistrc` file itself rather than the Baseline date, meaning the list of browsers would be frozen until we explicitly update it between majors.

Author: dgp1130

modules/testing/builder/projects/hello-world-app/.browserslistrc

@@ -99,6 +99,7 @@
     "ajv": "8.17.1",
     "ansi-colors": "4.1.3",
     "beasties": "0.2.0",
+    "bl2bl": "^0.2.0",
     "buffer": "6.0.3",
     "esbuild": "0.25.2",
     "esbuild-wasm": "0.25.2",
@@ -173,9 +174,18 @@
           "rxjs": "*"
         }
       }
+    },
+    "patchedDependencies": {
+      "bl2bl": "patches/bl2bl.patch"
     }
   },
   "resolutions": {
     "typescript": "5.8.2"
+  },
+  "bl2bl": {
+    "baselineThreshold": "widely available",
+    "useBrowserslistrc": false,
+    "downstreamBrowsers": false,
+    "savePrevious": true
   }
 }

package.json

@@ -1,4 +1,5 @@
 load("@devinfra//bazel/api-golden:index_rjs.bzl", "api_golden_test_npm_package")
+load("@npm2//:bl2bl/package_json.bzl", bl2bl_bin = "bin")
 load("@npm2//:defs.bzl", "npm_link_all_packages")
 load("//tools:defaults2.bzl", "copy_to_bin", "jasmine_test", "npm_package", "ts_project")
 load("//tools:ts_json_schema.bzl", "ts_json_schema")
@@ -39,6 +40,13 @@ copy_to_bin(
     srcs = glob(["**/schema.json"]),
 )
 
+bl2bl_bin.bl2bl(
+    name = "angular_browserslist",
+    srcs = ["src/browserslist/package.json"],
+    outs = ["src/browserslist/.browserslistrc"],
+    chdir = "%s/src/browserslist" % package_name(),
+)
+
 RUNTIME_ASSETS = glob(
     include = [
         "src/**/schema.json",
@@ -49,6 +57,7 @@ RUNTIME_ASSETS = glob(
 ) + [
     "builders.json",
     "package.json",
+    ":angular_browserslist",
 ]
 
 ts_project(

packages/angular/build/BUILD.bazel

@@ -0,0 +1,8 @@
+{
+  "bl2bl": {
+    "baselineThreshold": "2025-03-31",
+    "useBrowserslistrc": true,
+    "downstreamBrowsers": false,
+    "savePrevious": false
+  }
+}

packages/angular/build/src/browserslist/package.json

@@ -59,7 +59,7 @@ export async function executeBuild(
   } = options;
 
   // TODO: Consider integrating into watch mode. Would require full rebuild on target changes.
-  const browsers = getSupportedBrowsers(projectRoot, context.logger);
+  const browsers = await getSupportedBrowsers(projectRoot, context.logger);
 
   // Load active translations if inlining
   // TODO: Integrate into watch mode and only load changed translations

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

@@ -84,13 +84,38 @@ describeBuilder(buildApplication, APPLICATION_BUILDER_INFO, (harness) => {
     });
 
     it('warns when IE is present in browserslist', async () => {
-      await harness.appendToFile(
+      await harness.writeFile(
         '.browserslistrc',
         `
-           IE 9
-           IE 11
-         `,
+IE 9
+IE 11
+        `.trim(),
+      );
+
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+      });
+
+      const { result, logs } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+
+      expect(logs).toContain(
+        jasmine.objectContaining({
+          level: 'warn',
+          message: jasmine.stringContaining('ES5 output is not supported'),
+        }),
+      );
+
+      // Don't duplicate the error.
+      expect(logs).not.toContain(
+        jasmine.objectContaining({
+          message: jasmine.stringContaining("fall outside Angular's browser support"),
+        }),
       );
+    });
+
+    it("warns when targeting a browser outside Angular's minimum support", async () => {
+      await harness.writeFile('.browserslistrc', 'Chrome >= 100');
 
       harness.useTarget('build', {
         ...BASE_OPTIONS,
@@ -102,10 +127,7 @@ describeBuilder(buildApplication, APPLICATION_BUILDER_INFO, (harness) => {
       expect(logs).toContain(
         jasmine.objectContaining({
           level: 'warn',
-          message:
-            `One or more browsers which are configured in the project's Browserslist ` +
-            'configuration will be ignored as ES5 output is not supported by the Angular CLI.\n' +
-            'Ignored browsers: ie 11, ie 9',
+          message: jasmine.stringContaining("fall outside Angular's browser support"),
         }),
       );
     });

packages/angular/build/src/builders/application/tests/behavior/browser-support_spec.ts

@@ -398,7 +398,7 @@ export async function* serveWithVite(
 
       const { root = '' } = await context.getProjectMetadata(projectName);
       const projectRoot = join(context.workspaceRoot, root as string);
-      const browsers = getSupportedBrowsers(projectRoot, context.logger);
+      const browsers = await getSupportedBrowsers(projectRoot, context.logger);
 
       const target = transformSupportedBrowsersToTargets(browsers);
       // Needed for browser-esbuild as polyfills can be a string.

packages/angular/build/src/builders/dev-server/vite-server.ts

@@ -7,40 +7,57 @@
  */
 
 import browserslist from 'browserslist';
+import { promises as fs } from 'fs';
 
-export function getSupportedBrowsers(
+export async function getSupportedBrowsers(
   projectRoot: string,
   logger: { warn(message: string): void },
-): string[] {
-  browserslist.defaults = [
-    'last 2 Chrome versions',
-    'last 1 Firefox version',
-    'last 2 Edge major versions',
-    'last 2 Safari major versions',
-    'last 2 iOS major versions',
-    'last 2 Android major versions',
-    'Firefox ESR',
-  ];
+): Promise<string[]> {
+  // Read the browserslist configuration containing Angular's browser support policy.
+  const angularBrowserslist = (
+    await fs.readFile(require.resolve('../browserslist/.browserslistrc'), 'utf8')
+  )
+    .split('\n')
+    .filter((line) => !line.startsWith('#')); // Omit comments.
+
+  // Use Angular's configuration as the default.
+  browserslist.defaults = angularBrowserslist;
+
+  // Get the minimum set of browser versions supported by Angular.
+  const minimumBrowsers = new Set(browserslist(angularBrowserslist));
 
   // Get browsers from config or default.
   const browsersFromConfigOrDefault = new Set(browserslist(undefined, { path: projectRoot }));
 
   // Get browsers that support ES6 modules.
   const browsersThatSupportEs6 = new Set(browserslist('supports es6-module'));
 
+  const nonEs6Browsers: string[] = [];
   const unsupportedBrowsers: string[] = [];
   for (const browser of browsersFromConfigOrDefault) {
     if (!browsersThatSupportEs6.has(browser)) {
+      // Any browser which does not support ES6 is explicitly ignored, as Angular will not build successfully.
       browsersFromConfigOrDefault.delete(browser);
+      nonEs6Browsers.push(browser);
+    } else if (!minimumBrowsers.has(browser)) {
+      // Any other unsupported browser we will attempt to use, but provide no support for.
       unsupportedBrowsers.push(browser);
     }
   }
 
-  if (unsupportedBrowsers.length) {
+  if (nonEs6Browsers.length) {
     logger.warn(
       `One or more browsers which are configured in the project's Browserslist configuration ` +
         'will be ignored as ES5 output is not supported by the Angular CLI.\n' +
-        `Ignored browsers: ${unsupportedBrowsers.join(', ')}`,
+        `Ignored browsers:\n${nonEs6Browsers.join(', ')}`,
+    );
+  }
+
+  if (unsupportedBrowsers.length) {
+    logger.warn(
+      `One or more browsers which are configured in the project's Browserslist configuration ` +
+        "fall outside Angular's browser support for this version.\n" +
+        `Unsupported browsers:\n${unsupportedBrowsers.join(', ')}`,
     );
   }
 

packages/angular/build/src/utils/supported-browsers.ts

@@ -36,14 +36,14 @@ export type NormalizedBrowserBuilderSchema = BrowserBuilderSchema &
     polyfills: string[];
   };
 
-export function normalizeBrowserSchema(
+export async function normalizeBrowserSchema(
   workspaceRoot: string,
   projectRoot: string,
   projectSourceRoot: string | undefined,
   options: BrowserBuilderSchema,
   metadata: json.JsonObject,
   logger: logging.LoggerApi,
-): NormalizedBrowserBuilderSchema {
+): Promise<NormalizedBrowserBuilderSchema> {
   return {
     ...options,
     cache: normalizeCacheOptions(metadata, workspaceRoot),
@@ -73,6 +73,6 @@ export function normalizeBrowserSchema(
     // A value of 0 is falsy and will disable polling rather then enable
     // 500 ms is a sensible default in this case
     poll: options.poll === 0 ? 500 : options.poll,
-    supportedBrowsers: getSupportedBrowsers(projectRoot, logger),
+    supportedBrowsers: await getSupportedBrowsers(projectRoot, logger),
   };
 }

packages/angular_devkit/build_angular/src/utils/normalize-builder-schema.ts

@@ -145,7 +145,7 @@ export async function generateBrowserWebpackConfigFromContext(
   const sourceRoot = projectMetadata.sourceRoot as string | undefined;
   const projectSourceRoot = sourceRoot ? path.join(workspaceRoot, sourceRoot) : undefined;
 
-  const normalizedOptions = normalizeBrowserSchema(
+  const normalizedOptions = await normalizeBrowserSchema(
     workspaceRoot,
     projectRoot,
     projectSourceRoot,

packages/angular_devkit/build_angular/src/utils/webpack-browser-config.ts

@@ -0,0 +1,21 @@
+diff --git a/bin/cli.js b/bin/cli.js
+index d1a554e6de9e9b4497ffeae5476b3e838c79b408..2bd1955d7120a7992fe6676b1d4da47a7be1b153 100755
+--- a/bin/cli.js
++++ b/bin/cli.js
+@@ -114,6 +114,7 @@ import("baseline-browser-mapping").then((bbm) => {
+   });
+ 
+   // Behaviour varies depending on whether userBrowserslistrc=true or false
++  const originallyHadBrowserslistrc = Boolean(packageJSON["browserslist"]);
+   if (!bl2blConfig.useBrowserslistrc) {
+     // if false, add baselineVersions to packageJSON object for later
+     packageJSON["browserslist"] = browserslistOutput;
+@@ -149,7 +150,7 @@ import("baseline-browser-mapping").then((bbm) => {
+   }
+ 
+   // Whatever happens, update package.json as long as the packageJSON object isn't null
+-  if (packageJSON != null) {
++  if (packageJSON != null && (!bl2blConfig.useBrowserslistrc || originallyHadBrowserslistrc)) {
+     fs.writeFileSync(
+       process.cwd() + "/package.json",
+       JSON.stringify(packageJSON, null, 2),