feat(@angular-devkit/build-angular): allow control of Vite-based development server prebundling

Previously, the Vite-based development server that is automatically used with the `application`
and `browser-esbuild` builders would always use prebundling if the Angular CLI caching was enabled.
The development server now has a specific `prebundle` option to allow more control over prebundling
while still allowing other forms of caching within the Angular CLI. The `prebundle` option
can be a boolean value of `true` or `false` that will enable or disable prebundling, respectively.
Additionally, the option also has an object long-form. This long-form enables prebundling and
currently contains one property named `exclude`. The `exclude` property supports cases where a
package should not be prebundled and rather should be bundled directly into the application code.
These cases are not common but can happen based on project specific requirements.
If the `prebundle` option is enabled when using the `browser` builder or any other Webpack-based
builder, it will be ignored as the Webpack-based development server does not contain such
functionality.

Author: clydin

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

@@ -182,6 +182,7 @@ export interface DevServerBuilderOptions {
     open?: boolean;
     poll?: number;
     port?: number;
+    prebundle?: PrebundleUnion;
     proxyConfig?: string;
     publicHost?: string;
     servePath?: string;

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

@@ -69,13 +69,27 @@ export function execute(
           );
         }
 
+        // Warn if the initial options provided by the user enable prebundling but caching is disabled
+        if (options.prebundle && !normalizedOptions.cacheOptions.enabled) {
+          context.logger.warn(
+            `Prebundling has been configured but will not be used because caching has been disabled.`,
+          );
+        }
+
         return defer(() => import('./vite-server')).pipe(
           switchMap(({ serveWithVite }) =>
             serveWithVite(normalizedOptions, builderName, context, transforms, extensions),
           ),
         );
       }
 
+      // Warn if the initial options provided by the user enable prebundling with Webpack-based builders
+      if (options.prebundle) {
+        context.logger.warn(
+          `Prebundling has been configured but will not be used because it is not supported by the "${builderName}" builder.`,
+        );
+      }
+
       if (extensions?.buildPlugins?.length) {
         throw new Error('Only the `application` and `browser-esbuild` builders support plugins.');
       }
@@ -105,7 +119,13 @@ async function initialize(
   await purgeStaleBuildCache(context);
 
   const normalizedOptions = await normalizeOptions(context, projectName, initialOptions);
-  const builderName = await context.getBuilderNameForTarget(normalizedOptions.buildTarget);
+  const builderName = builderSelector(
+    {
+      builderName: await context.getBuilderNameForTarget(normalizedOptions.buildTarget),
+      forceEsbuild: !!normalizedOptions.forceEsbuild,
+    },
+    context.logger,
+  );
 
   if (
     !normalizedOptions.disableHostCheck &&
@@ -133,10 +153,7 @@ case.
   normalizedOptions.port = await checkPort(normalizedOptions.port, normalizedOptions.host);
 
   return {
-    builderName: builderSelector(
-      { builderName, forceEsbuild: !!normalizedOptions.forceEsbuild },
-      context.logger,
-    ),
+    builderName,
     normalizedOptions,
   };
 }

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

@@ -58,6 +58,7 @@ export async function normalizeOptions(
     sslCert,
     sslKey,
     forceEsbuild,
+    prebundle,
   } = options;
 
   // Return all the normalized options
@@ -84,5 +85,7 @@ export async function normalizeOptions(
     sslCert,
     sslKey,
     forceEsbuild,
+    // Prebundling defaults to true but requires caching to function
+    prebundle: cacheOptions.enabled && (prebundle ?? true),
   };
 }

packages/angular_devkit/build_angular/src/builders/dev-server/schema.json

@@ -106,6 +106,24 @@
       "type": "boolean",
       "description": "Force the development server to use the 'browser-esbuild' builder when building. This is a developer preview option for the esbuild-based build system.",
       "default": false
+    },
+    "prebundle": {
+      "description": "Enable and control the Vite-based development server's prebundling capabilities. To enable prebundling, the Angular CLI cache must also be enabled. This option has no effect when using the 'browser' or other Webpack-based builders.",
+      "oneOf": [
+        { "type": "boolean" },
+        {
+          "type": "object",
+          "properties": {
+            "exclude": {
+              "description": "List of package imports that should not be prebundled by the development server. The packages will be bundled into the application code itself.",
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false,
+          "required": ["exclude"]
+        }
+      ]
     }
   },
   "additionalProperties": false,

packages/angular_devkit/build_angular/src/builders/dev-server/tests/execute-fetch.ts

@@ -18,20 +18,24 @@ export async function executeOnceAndFetch<T>(
   harness: BuilderHarness<T>,
   url: string,
   options?: Partial<BuilderHarnessExecutionOptions> & { request?: RequestInit },
-): Promise<BuilderHarnessExecutionResult & { response?: Response }> {
+): Promise<BuilderHarnessExecutionResult & { response?: Response; content?: string }> {
   return lastValueFrom(
     harness.execute().pipe(
       timeout(30000),
       mergeMap(async (executionResult) => {
         let response = undefined;
+        let content = undefined;
         if (executionResult.result?.success) {
           let baseUrl = `${executionResult.result.baseUrl}`;
           baseUrl = baseUrl[baseUrl.length - 1] === '/' ? baseUrl : `${baseUrl}/`;
           const resolvedUrl = new URL(url, baseUrl);
-          response = await fetch(resolvedUrl, options?.request);
+          const originalResponse = await fetch(resolvedUrl, options?.request);
+          response = originalResponse.clone();
+          // Ensure all data is available before stopping server
+          content = await originalResponse.text();
         }
 
-        return { ...executionResult, response };
+        return { ...executionResult, response, content };
       }),
       take(1),
     ),

packages/angular_devkit/build_angular/src/builders/dev-server/tests/options/prebundle_spec.ts

@@ -0,0 +1,99 @@
+/**
+ * @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 { executeDevServer } from '../../index';
+import { executeOnceAndFetch } from '../execute-fetch';
+import { describeServeBuilder } from '../jasmine-helpers';
+import { BASE_OPTIONS, DEV_SERVER_BUILDER_INFO } from '../setup';
+
+// TODO: Temporarily disabled pending investigation into test-only Vite not stopping when caching is enabled
+describeServeBuilder(
+  executeDevServer,
+  DEV_SERVER_BUILDER_INFO,
+  (harness, setupTarget, isViteRun) => {
+    // prebundling is not available in webpack
+    (isViteRun ? xdescribe : xdescribe)('option: "prebundle"', () => {
+      beforeEach(async () => {
+        setupTarget(harness);
+
+        harness.useProject('test', {
+          cli: {
+            cache: {
+              enabled: true,
+            },
+          },
+        });
+
+        // Application code is not needed for these tests
+        await harness.writeFile(
+          'src/main.ts',
+          `
+          import { VERSION as coreVersion } from '@angular/core';
+          import { VERSION as platformVersion } from '@angular/platform-browser';
+
+          console.log(coreVersion);
+          console.log(platformVersion);
+        `,
+        );
+      });
+
+      it('should prebundle dependencies when option is not present', async () => {
+        harness.useTarget('serve', {
+          ...BASE_OPTIONS,
+        });
+
+        const { result, content } = await executeOnceAndFetch(harness, '/main.js');
+
+        expect(result?.success).toBeTrue();
+        expect(content).toContain('vite/deps/@angular_core.js');
+        expect(content).not.toContain('node_modules/@angular/core/');
+      });
+
+      it('should prebundle dependencies when option is set to true', async () => {
+        harness.useTarget('serve', {
+          ...BASE_OPTIONS,
+          prebundle: true,
+        });
+
+        const { result, content } = await executeOnceAndFetch(harness, '/main.js');
+
+        expect(result?.success).toBeTrue();
+        expect(content).toContain('vite/deps/@angular_core.js');
+        expect(content).not.toContain('node_modules/@angular/core/');
+      });
+
+      it('should not prebundle dependencies when option is set to false', async () => {
+        harness.useTarget('serve', {
+          ...BASE_OPTIONS,
+          prebundle: false,
+        });
+
+        const { result, content } = await executeOnceAndFetch(harness, '/main.js');
+
+        expect(result?.success).toBeTrue();
+        expect(content).not.toContain('vite/deps/@angular_core.js');
+        expect(content).toContain('node_modules/@angular/core/');
+      });
+
+      it('should not prebundle specified dependency if added to exclude list', async () => {
+        harness.useTarget('serve', {
+          ...BASE_OPTIONS,
+          prebundle: { exclude: ['@angular/platform-browser'] },
+        });
+
+        const { result, content } = await executeOnceAndFetch(harness, '/main.js');
+
+        expect(result?.success).toBeTrue();
+        expect(content).toContain('vite/deps/@angular_core.js');
+        expect(content).not.toContain('node_modules/@angular/core/');
+        expect(content).not.toContain('vite/deps/@angular_platform-browser.js');
+        expect(content).toContain('node_modules/@angular/platform-browser/');
+      });
+    });
+  },
+);

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

@@ -80,7 +80,7 @@ export async function* serveWithVite(
   }
 
   // Set all packages as external to support Vite's prebundle caching
-  browserOptions.externalPackages = serverOptions.cacheOptions.enabled;
+  browserOptions.externalPackages = serverOptions.prebundle as json.JsonValue;
 
   const baseHref = browserOptions.baseHref;
   if (serverOptions.servePath === undefined && baseHref !== undefined) {
@@ -513,7 +513,7 @@ export async function setupServer(
          */
 
         // Only enable with caching since it causes prebundle dependencies to be cached
-        disabled: true, // !serverOptions.cacheOptions.enabled,
+        disabled: true, // serverOptions.prebundle === false,
         // Exclude any explicitly defined dependencies (currently build defined externals and node.js built-ins)
         exclude: serverExplicitExternal,
         // Include all implict dependencies from the external packages internal option
@@ -543,7 +543,7 @@ export async function setupServer(
     // Browser only optimizeDeps. (This does not run for SSR dependencies).
     optimizeDeps: getDepOptimizationConfig({
       // Only enable with caching since it causes prebundle dependencies to be cached
-      disabled: !serverOptions.cacheOptions.enabled,
+      disabled: serverOptions.prebundle === false,
       // Exclude any explicitly defined dependencies (currently build defined externals)
       exclude: externalMetadata.explicit,
       // Include all implict dependencies from the external packages internal option