refactor(@angular-devkit/build-angular): add experimental extension points to Vite-based dev server

When using the experimental programmatic API for the development server with an esbuild-based
builder (`application`/`browser-esbuild`), express compatible middleware can now be added.
Also, the index HTML transformer that previously only worked with the Webpack-based development
server is also now enabled.
However, usage of these options may result in unexpected application output and/or build failures.
They are also not officially supported and SemVer guarantees are not present.
Stable and supported methods for build process extension are being evaluated for a future release.

Author: clydin

goldens/public-api/angular_devkit/build_angular/index.md

@@ -4,11 +4,14 @@
 
 ```ts
 
+/// <reference types="node" />
+
 import { BuilderContext } from '@angular-devkit/architect';
 import { BuilderOutput } from '@angular-devkit/architect';
 import type { ConfigOptions } from 'karma';
 import { Configuration } from 'webpack';
 import { DevServerBuildOutput } from '@angular-devkit/build-webpack';
+import type http from 'node:http';
 import { json } from '@angular-devkit/core';
 import { Observable } from 'rxjs';
 import { OutputFile } from 'esbuild';
@@ -204,7 +207,10 @@ export function executeDevServerBuilder(options: DevServerBuilderOptions, contex
     webpackConfiguration?: ExecutionTransformer<Configuration>;
     logging?: WebpackLoggingCallback;
     indexHtml?: IndexHtmlTransform;
-}, plugins?: Plugin_2[]): Observable<DevServerBuilderOutput>;
+}, extensions?: {
+    buildPlugins?: Plugin_2[];
+    middleware?: ((req: http.IncomingMessage, res: http.ServerResponse, next: (err?: unknown) => void) => void)[];
+}): Observable<DevServerBuilderOutput>;
 
 // @public
 export function executeExtractI18nBuilder(options: ExtractI18nBuilderOptions, context: BuilderContext, transforms?: {

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

@@ -8,6 +8,7 @@
 
 import type { BuilderContext } from '@angular-devkit/architect';
 import type { Plugin } from 'esbuild';
+import type http from 'node:http';
 import { EMPTY, Observable, defer, switchMap } from 'rxjs';
 import type { ExecutionTransformer } from '../../transforms';
 import { checkPort } from '../../utils/check-port';
@@ -19,10 +20,16 @@ import type { DevServerBuilderOutput } from './webpack-server';
 
 /**
  * A Builder that executes a development server based on the provided browser target option.
+ *
+ * Usage of the `transforms` and/or `extensions` parameters is NOT supported and may cause
+ * unexpected build output or build failures.
+ *
  * @param options Dev Server options.
  * @param context The build context.
  * @param transforms A map of transforms that can be used to hook into some logic (such as
  * transforming webpack configuration before passing it to webpack).
+ * @param extensions An optional object containing an array of build plugins (esbuild-based)
+ * and/or HTTP request middleware.
  *
  * @experimental Direct usage of this function is considered experimental.
  */
@@ -34,7 +41,14 @@ export function execute(
     logging?: import('@angular-devkit/build-webpack').WebpackLoggingCallback;
     indexHtml?: IndexHtmlTransform;
   } = {},
-  plugins?: Plugin[],
+  extensions?: {
+    buildPlugins?: Plugin[];
+    middleware?: ((
+      req: http.IncomingMessage,
+      res: http.ServerResponse,
+      next: (err?: unknown) => void,
+    ) => void)[];
+  },
 ): Observable<DevServerBuilderOutput> {
   // Determine project name from builder context target
   const projectName = context.target?.project;
@@ -52,22 +66,27 @@ export function execute(
         builderName === '@angular-devkit/build-angular:browser-esbuild' ||
         normalizedOptions.forceEsbuild
       ) {
-        if (Object.keys(transforms).length > 0) {
+        if (transforms?.logging || transforms?.webpackConfiguration) {
           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, plugins),
+            serveWithVite(normalizedOptions, builderName, context, transforms, extensions),
           ),
         );
       }
 
-      if (plugins?.length) {
+      if (extensions?.buildPlugins?.length) {
         throw new Error('Only the `application` and `browser-esbuild` builders support plugins.');
       }
+      if (extensions?.middleware?.length) {
+        throw new Error(
+          'Only the `application` and `browser-esbuild` builders support middleware.',
+        );
+      }
 
       // Use Webpack for all other browser targets
       return defer(() => import('./webpack-server')).pipe(

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

@@ -40,11 +40,18 @@ interface OutputFileRecord {
   servable: boolean;
 }
 
+// eslint-disable-next-line max-lines-per-function
 export async function* serveWithVite(
   serverOptions: NormalizedDevServerOptions,
   builderName: string,
   context: BuilderContext,
-  plugins?: Plugin[],
+  transformers?: {
+    indexHtml?: (content: string) => Promise<string>;
+  },
+  extensions?: {
+    middleware?: Connect.NextHandleFunction[];
+    buildPlugins?: Plugin[];
+  },
 ): AsyncIterableIterator<DevServerBuilderOutput> {
   // Get the browser configuration from the target name.
   const rawBrowserOptions = (await context.getTargetOptions(
@@ -133,7 +140,7 @@ export async function* serveWithVite(
     {
       write: false,
     },
-    plugins,
+    extensions?.buildPlugins,
   )) {
     assert(result.outputFiles, 'Builder did not provide result files.');
 
@@ -207,6 +214,8 @@ export async function* serveWithVite(
         !!browserOptions.ssr,
         prebundleTransformer,
         target,
+        extensions?.middleware,
+        transformers?.indexHtml,
       );
 
       server = await createServer(serverConfiguration);
@@ -366,6 +375,8 @@ export async function setupServer(
   ssr: boolean,
   prebundleTransformer: JavaScriptTransformer,
   target: string[],
+  extensionMiddleware?: Connect.NextHandleFunction[],
+  indexHtmlTransformer?: (content: string) => Promise<string>,
 ): Promise<InlineConfig> {
   const proxy = await loadProxyConfiguration(
     serverOptions.workspaceRoot,
@@ -557,6 +568,10 @@ export async function setupServer(
             next();
           });
 
+          if (extensionMiddleware?.length) {
+            extensionMiddleware.forEach((middleware) => server.middlewares.use(middleware));
+          }
+
           // Returning a function, installs middleware after the main transform middleware but
           // before the built-in HTML middleware
           return () => {
@@ -595,7 +610,9 @@ export async function setupServer(
                   inlineCriticalCss: false,
                 });
 
-                return content;
+                return indexHtmlTransformer && content
+                  ? await indexHtmlTransformer(content)
+                  : content;
               });
             }
 
@@ -617,7 +634,13 @@ export async function setupServer(
               if (pathname === '/' || pathname === `/index.html`) {
                 const rawHtml = outputFiles.get('/index.html')?.contents;
                 if (rawHtml) {
-                  transformIndexHtmlAndAddHeaders(req.url, rawHtml, res, next);
+                  transformIndexHtmlAndAddHeaders(
+                    req.url,
+                    rawHtml,
+                    res,
+                    next,
+                    indexHtmlTransformer,
+                  );
 
                   return;
                 }