refactor(@angular-devkit/build-angular): export application builder for experimental programmatic usage

Similar to the existing Webpack-based `browser` builder, the new `application` builder is also exported
from the `@angular-devkit/build-angular` package for use programmatically. As is the case for the existing
builder JavaScript exports from the package, the new export (`buildApplication`) is also considered experimental
and does not provide the support nor semver guarantees that the builders have when used via `angular.json` configuration.
The usage of the `plugins` parameter of the `buildApplication` allows adding esbuild compatible plugins to the end
of the plugin list for the main application code bundling. However, usage of the parameter may result in unexpected application
output and/or build failures. Stable and supported methods for build process extension are being evaluated for a future release.

Author: clydin

packages/angular_devkit/build_angular/src/builders/application/index.ts

@@ -7,6 +7,7 @@
  */
 
 import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
+import type { Plugin } from 'esbuild';
 import { BuildOutputFile, BuildOutputFileType } from '../../tools/esbuild/bundler-context';
 import { purgeStaleBuildCache } from '../../utils/purge-cache';
 import { assertCompatibleAngularVersion } from '../../utils/version';
@@ -15,13 +16,16 @@ import { executeBuild } from './execute-build';
 import { ApplicationBuilderInternalOptions, normalizeOptions } from './options';
 import { Schema as ApplicationBuilderOptions } from './schema';
 
+export { ApplicationBuilderOptions };
+
 export async function* buildApplicationInternal(
   options: ApplicationBuilderInternalOptions,
   // TODO: Integrate abort signal support into builder system
   context: BuilderContext & { signal?: AbortSignal },
   infrastructureSettings?: {
     write?: boolean;
   },
+  plugins?: Plugin[],
 ): AsyncIterable<
   BuilderOutput & {
     outputFiles?: BuildOutputFile[];
@@ -42,7 +46,7 @@ export async function* buildApplicationInternal(
     return;
   }
 
-  const normalizedOptions = await normalizeOptions(context, projectName, options);
+  const normalizedOptions = await normalizeOptions(context, projectName, options, plugins);
 
   yield* runEsBuildBuildAction(
     (rebuildState) => executeBuild(normalizedOptions, context, rebuildState),
@@ -69,16 +73,31 @@ export async function* buildApplicationInternal(
   );
 }
 
+/**
+ * Builds an application using the `application` builder with the provided
+ * options.
+ *
+ * Usage of the `plugins` parameter is NOT supported and may cause unexpected
+ * build output or build failures.
+ *
+ * @experimental Direct usage of this function is considered experimental.
+ *
+ * @param options The options defined by the builder's schema to use.
+ * @param context An Architect builder context instance.
+ * @param plugins An array of plugins to apply to the main code bundling.
+ * @returns The build output results of the build.
+ */
 export function buildApplication(
   options: ApplicationBuilderOptions,
   context: BuilderContext,
+  plugins?: Plugin[],
 ): AsyncIterable<
   BuilderOutput & {
     outputFiles?: BuildOutputFile[];
     assetFiles?: { source: string; destination: string }[];
   }
 > {
-  return buildApplicationInternal(options, context);
+  return buildApplicationInternal(options, context, undefined, plugins);
 }
 
 export default createBuilder(buildApplication);

packages/angular_devkit/build_angular/src/builders/application/options.ts

@@ -7,6 +7,7 @@
  */
 
 import { BuilderContext } from '@angular-devkit/architect';
+import type { Plugin } from 'esbuild';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import {
@@ -71,13 +72,15 @@ export type ApplicationBuilderInternalOptions = Omit<
  * @param context The context for current builder execution.
  * @param projectName The name of the project for the current execution.
  * @param options An object containing the options to use for the build.
+ * @param plugins An optional array of programmatically supplied build plugins.
  * @returns An object containing normalized options required to perform the build.
  */
 // eslint-disable-next-line max-lines-per-function
 export async function normalizeOptions(
   context: BuilderContext,
   projectName: string,
   options: ApplicationBuilderInternalOptions,
+  plugins?: Plugin[],
 ) {
   const workspaceRoot = context.workspaceRoot;
   const projectMetadata = await context.getProjectMetadata(projectName);
@@ -295,6 +298,7 @@ export async function normalizeOptions(
     namedChunks,
     budgets: budgets?.length ? budgets : undefined,
     publicPath: deployUrl ? deployUrl : undefined,
+    plugins: plugins?.length ? plugins : undefined,
   };
 }
 

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

@@ -7,6 +7,7 @@
  */
 
 import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
+import type { Plugin } from 'esbuild';
 import { constants as fsConstants } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -29,6 +30,7 @@ export async function* buildEsbuildBrowser(
   infrastructureSettings?: {
     write?: boolean;
   },
+  plugins?: Plugin[],
 ): AsyncIterable<
   BuilderOutput & {
     outputFiles?: BuildOutputFile[];
@@ -40,9 +42,14 @@ export async function* buildEsbuildBrowser(
   const normalizedOptions = normalizeOptions(userOptions);
   const fullOutputPath = path.join(context.workspaceRoot, normalizedOptions.outputPath);
 
-  for await (const result of buildApplicationInternal(normalizedOptions, context, {
-    write: false,
-  })) {
+  for await (const result of buildApplicationInternal(
+    normalizedOptions,
+    context,
+    {
+      write: false,
+    },
+    plugins,
+  )) {
     if (infrastructureSettings?.write !== false && result.outputFiles) {
       // Write output files
       await writeResultFiles(result.outputFiles, result.assetFiles, fullOutputPath);

packages/angular_devkit/build_angular/src/builders/dev-server/builder.ts

@@ -7,6 +7,7 @@
  */
 
 import type { BuilderContext } from '@angular-devkit/architect';
+import type { Plugin } from 'esbuild';
 import { EMPTY, Observable, defer, switchMap } from 'rxjs';
 import type { ExecutionTransformer } from '../../transforms';
 import { checkPort } from '../../utils/check-port';
@@ -33,6 +34,7 @@ export function execute(
     logging?: import('@angular-devkit/build-webpack').WebpackLoggingCallback;
     indexHtml?: IndexHtmlTransform;
   } = {},
+  plugins?: Plugin[],
 ): Observable<DevServerBuilderOutput> {
   // Determine project name from builder context target
   const projectName = context.target?.project;
@@ -50,11 +52,23 @@ export function execute(
         builderName === '@angular-devkit/build-angular:browser-esbuild' ||
         normalizedOptions.forceEsbuild
       ) {
+        if (Object.keys(transforms).length > 0) {
+          throw new Error(
+            'The `application` and `browser-esbuild` builders do not support Webpack transforms.',
+          );
+        }
+
         return defer(() => import('./vite-server')).pipe(
-          switchMap(({ serveWithVite }) => serveWithVite(normalizedOptions, builderName, context)),
+          switchMap(({ serveWithVite }) =>
+            serveWithVite(normalizedOptions, builderName, context, plugins),
+          ),
         );
       }
 
+      if (plugins?.length) {
+        throw new Error('Only the `application` and `browser-esbuild` builders support plugins.');
+      }
+
       // Use Webpack for all other browser targets
       return defer(() => import('./webpack-server')).pipe(
         switchMap(({ serveWebpackBrowser }) =>

packages/angular_devkit/build_angular/src/builders/dev-server/vite-server.ts

@@ -8,6 +8,7 @@
 
 import type { BuilderContext } from '@angular-devkit/architect';
 import type { json, logging } from '@angular-devkit/core';
+import type { Plugin } from 'esbuild';
 import { lookup as lookupMimeType } from 'mrmime';
 import assert from 'node:assert';
 import { BinaryLike, createHash } from 'node:crypto';
@@ -48,6 +49,7 @@ export async function* serveWithVite(
   serverOptions: NormalizedDevServerOptions,
   builderName: string,
   context: BuilderContext,
+  plugins?: Plugin[],
 ): AsyncIterableIterator<DevServerBuilderOutput> {
   // Get the browser configuration from the target name.
   const rawBrowserOptions = (await context.getTargetOptions(
@@ -115,9 +117,14 @@ export async function* serveWithVite(
   const generatedFiles = new Map<string, OutputFileRecord>();
   const assetFiles = new Map<string, string>();
   // TODO: Switch this to an architect schedule call when infrastructure settings are supported
-  for await (const result of buildEsbuildBrowser(browserOptions, context, {
-    write: false,
-  })) {
+  for await (const result of buildEsbuildBrowser(
+    browserOptions,
+    context,
+    {
+      write: false,
+    },
+    plugins,
+  )) {
     assert(result.outputFiles, 'Builder did not provide result files.');
 
     // Analyze result files for changes

packages/angular_devkit/build_angular/src/index.ts

@@ -29,6 +29,8 @@ export {
   BrowserBuilderOutput,
 } from './builders/browser';
 
+export { buildApplication, ApplicationBuilderOptions } from './builders/application';
+
 export {
   executeDevServerBuilder,
   DevServerBuilderOptions,

packages/angular_devkit/build_angular/src/tools/esbuild/application-code-bundle.ts

@@ -165,6 +165,10 @@ export function createBrowserCodeBundleOptions(
     );
   }
 
+  if (options.plugins) {
+    buildOptions.plugins?.push(...options.plugins);
+  }
+
   return buildOptions;
 }
 
@@ -343,6 +347,10 @@ export function createServerCodeBundleOptions(
     );
   }
 
+  if (options.plugins) {
+    buildOptions.plugins.push(...options.plugins);
+  }
+
   return buildOptions;
 }