refactor: add baseline_browserslist tool

This tool uses `baseline-browser-mapping` to generate a `browserslist` configuration at build time from a given widely-available Baseline date.

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 `baseline-browser-mapping` as part of the build process means there is a potential risk that a bugfix in the package 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: clydin

.bazelignore

@@ -17,4 +17,5 @@ packages/ngtools/webpack/node_modules
 packages/schematics/angular/node_modules
 modules/testing/builder/node_modules
 tests/node_modules
+tools/baseline_browserslist/node_modules
 tools/legacy-rnjs/node_modules

WORKSPACE

@@ -169,6 +169,7 @@ npm_translate_lock(
         "//packages/ngtools/webpack:package.json",
         "//packages/schematics/angular:package.json",
         "//tests:package.json",
+        "//tools/baseline_browserslist:package.json",
     ],
     lifecycle_hooks_envs = {
         # TODO: Standardize browser management for `rules_js`

pnpm-lock.yaml

@@ -15,3 +15,4 @@ packages:
   - packages/ngtools/webpack
   - modules/testing/builder
   - tests
+  - tools/baseline_browserslist

pnpm-workspace.yaml

@@ -0,0 +1,52 @@
+load("@aspect_rules_js//js:defs.bzl", "js_binary")
+load("@aspect_rules_ts//ts:defs.bzl", "ts_config")
+load("@npm2//:defs.bzl", "npm_link_all_packages")
+load("//tools:defaults.bzl", "jasmine_test", "ts_project")
+
+npm_link_all_packages()
+
+js_binary(
+    name = "baseline_browserslist",
+    data = [":baseline_browserslist_lib"],
+    entry_point = "index.mjs",
+    visibility = ["//:__subpackages__"],
+)
+
+ts_project(
+    name = "baseline_browserslist_lib",
+    srcs = [
+        "generate_browserslist.mts",
+        "index.mts",
+    ],
+    source_map = True,
+    tsconfig = ":build_tsconfig",
+    deps = [":node_modules/baseline-browser-mapping"],
+)
+
+ts_project(
+    name = "baseline_browserslist_test_lib",
+    testonly = True,
+    srcs = ["generate_browserslist_spec.mts"],
+    tsconfig = ":test_tsconfig",
+    deps = [":baseline_browserslist_lib"],
+)
+
+jasmine_test(
+    name = "baseline_browserslist_test",
+    data = [":baseline_browserslist_test_lib"],
+)
+
+ts_config(
+    name = "build_tsconfig",
+    src = "tsconfig-build.json",
+    deps = [
+        "//:build-tsconfig-esm",
+        "//:node_modules/@types/node",
+    ],
+)
+
+ts_config(
+    name = "test_tsconfig",
+    src = "tsconfig-test.json",
+    deps = ["//:test-tsconfig-esm"],
+)

tools/baseline_browserslist/BUILD.bazel

@@ -0,0 +1,26 @@
+"""Generates a `browserslist` configuration from a Baseline date."""
+
+load("@aspect_rules_js//js:defs.bzl", "js_run_binary")
+
+def baseline_browserslist(name, baseline, out, **kwargs):
+    """Generates a `browserslist` configuration from a Baseline date.
+
+    Args:
+        name: Name of this target.
+        baseline: A string date in "YYYY-MM-DD" format of the Baseline widely
+            available browser set to use in the generated `browserslist`.
+        out: Name of the output browserslist file. Prefer using `.browserslistrc`
+            for the output as the `browserslist` package seems to not like files
+            with a different name, even when explicitly provided.
+
+    See: https://web.dev/baseline
+    """
+
+    js_run_binary(
+        name = name,
+        srcs = [],
+        tool = Label(":baseline_browserslist"),
+        stdout = out,
+        args = [baseline],
+        **kwargs
+    )

tools/baseline_browserslist/baseline_browserslist.bzl

@@ -0,0 +1,38 @@
+/**
+ * @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 { getCompatibleVersions } from 'baseline-browser-mapping';
+
+// Map `baseline-browser-mapping` browsers to `browserslist` browsers.
+const browsers: Record<string, string> = {
+  chrome: 'Chrome',
+  chrome_android: 'ChromeAndroid',
+  edge: 'Edge',
+  firefox: 'Firefox',
+  firefox_android: 'FirefoxAndroid',
+  safari: 'Safari',
+  safari_ios: 'iOS',
+};
+
+/**
+ * Generates the `browserslist` configuration for the given Baseline date.
+ *
+ * @param date The Baseline "widely available" date to generate a `browserslist`
+ *     configuration for. Uses `YYYY-MM-DD` format.
+ * @returns The `browserslist` configuration file content.
+ */
+export function generateBrowserslist(date: string): string {
+  // Generate a `browserslist` configuration.
+  return getCompatibleVersions({
+    widelyAvailableOnDate: date,
+    includeDownstreamBrowsers: false,
+  })
+    .filter(({ browser }) => browsers[browser])
+    .map(({ browser, version }) => `${browsers[browser]} >= ${version}`)
+    .join('\n');
+}

tools/baseline_browserslist/generate_browserslist.mts

@@ -0,0 +1,27 @@
+/**
+ * @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 { generateBrowserslist } from './generate_browserslist.mjs';
+
+describe('generate_browserslist', () => {
+  describe('generateBrowserslist', () => {
+    it('generates a `browserslist` file', () => {
+      expect(generateBrowserslist('2025-03-31').trim()).toBe(
+        `
+Chrome >= 107
+ChromeAndroid >= 107
+Edge >= 107
+Firefox >= 104
+FirefoxAndroid >= 104
+Safari >= 16
+iOS >= 16
+        `.trim(),
+      );
+    });
+  });
+});

tools/baseline_browserslist/generate_browserslist_spec.mts

@@ -0,0 +1,15 @@
+/**
+ * @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 { generateBrowserslist } from './generate_browserslist.mjs';
+
+const [baselineDate] = process.argv.slice(2);
+const browserslist = generateBrowserslist(baselineDate);
+
+// eslint-disable-next-line no-console
+console.log(browserslist);

tools/baseline_browserslist/index.mts

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "devDependencies": {
+    "baseline-browser-mapping": "^2.2.0"
+  }
+}