fix(@angular-devkit/build-angular): process stylesheet resources from url tokens with esbuild browser builder

Stylesheet url tokens (`url(....)`) will now be processed when using the esbuild-based experimental browser
application builder. The paths will be resolved via the bundler's resolution system and then loaded
via the bundler's `file` loader. The functionality is implemented using an esbuild plugin to allow for all
file types to be supported without the need to manually specify each current and future file extension within
the build configuration.
The `externalDependencies` option also applies to the referenced resources. This allows for resource paths
specified with the option to remain unprocessed within the application output. This is useful if the relative
path for the resource does not exist on disk but will be available when the application is deployed.

Author: clydin

packages/angular_devkit/build_angular/src/builders/browser-esbuild/css-resource-plugin.ts

@@ -0,0 +1,62 @@
+/**
+ * @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.io/license
+ */
+
+import type { Plugin, PluginBuild } from 'esbuild';
+import { readFile } from 'fs/promises';
+
+/**
+ * Symbol marker used to indicate CSS resource resolution is being attempted.
+ * This is used to prevent an infinite loop within the plugin's resolve hook.
+ */
+const CSS_RESOURCE_RESOLUTION = Symbol('CSS_RESOURCE_RESOLUTION');
+
+/**
+ * Creates an esbuild {@link Plugin} that loads all CSS url token references using the
+ * built-in esbuild `file` loader. A plugin is used to allow for all file extensions
+ * and types to be supported without needing to manually specify all extensions
+ * within the build configuration.
+ *
+ * @returns An esbuild {@link Plugin} instance.
+ */
+export function createCssResourcePlugin(): Plugin {
+  return {
+    name: 'angular-css-resource',
+    setup(build: PluginBuild): void {
+      build.onResolve({ filter: /.*/ }, async (args) => {
+        // Only attempt to resolve url tokens which only exist inside CSS.
+        // Also, skip this plugin if already attempting to resolve the url-token.
+        if (args.kind !== 'url-token' || args.pluginData?.[CSS_RESOURCE_RESOLUTION]) {
+          return null;
+        }
+
+        const { importer, kind, resolveDir, namespace, pluginData = {} } = args;
+        pluginData[CSS_RESOURCE_RESOLUTION] = true;
+
+        const result = await build.resolve(args.path, {
+          importer,
+          kind,
+          namespace,
+          pluginData,
+          resolveDir,
+        });
+
+        return {
+          ...result,
+          namespace: 'css-resource',
+        };
+      });
+
+      build.onLoad({ filter: /.*/, namespace: 'css-resource' }, async (args) => {
+        return {
+          contents: await readFile(args.path),
+          loader: 'file',
+        };
+      });
+    },
+  };
+}

packages/angular_devkit/build_angular/src/builders/browser-esbuild/index.ts

@@ -168,6 +168,7 @@ export async function buildEsbuildBrowser(
           outputNames: noInjectNames.includes(name) ? { media: outputNames.media } : outputNames,
           includePaths: options.stylePreprocessorOptions?.includePaths,
           preserveSymlinks: options.preserveSymlinks,
+          externalDependencies: options.externalDependencies,
         },
       );
 
@@ -354,6 +355,7 @@ async function bundleCode(
             !!sourcemapOptions.styles && (sourcemapOptions.hidden ? false : 'inline'),
           outputNames,
           includePaths: options.stylePreprocessorOptions?.includePaths,
+          externalDependencies: options.externalDependencies,
         },
       ),
     ],

packages/angular_devkit/build_angular/src/builders/browser-esbuild/stylesheets.ts

@@ -8,6 +8,7 @@
 
 import type { BuildOptions, OutputFile } from 'esbuild';
 import * as path from 'path';
+import { createCssResourcePlugin } from './css-resource-plugin';
 import { bundle } from './esbuild';
 import { createSassPlugin } from './sass-plugin';
 
@@ -18,6 +19,7 @@ export interface BundleStylesheetOptions {
   sourcemap: boolean | 'external' | 'inline';
   outputNames?: { bundles?: string; media?: string };
   includePaths?: string[];
+  externalDependencies?: string[];
 }
 
 async function bundleStylesheet(
@@ -42,9 +44,13 @@ async function bundleStylesheet(
     write: false,
     platform: 'browser',
     preserveSymlinks: options.preserveSymlinks,
+    external: options.externalDependencies,
     conditions: ['style', 'sass'],
     mainFields: ['style', 'sass'],
-    plugins: [createSassPlugin({ sourcemap: !!options.sourcemap, loadPaths })],
+    plugins: [
+      createSassPlugin({ sourcemap: !!options.sourcemap, loadPaths }),
+      createCssResourcePlugin(),
+    ],
   });
 
   // Extract the result of the bundling from the output files