feat(@angular/build): enable chunk optimization by default with heuristics

Enable the advanced chunk optimization pass by default for applications with multiple lazy chunks to improve loading performance. A heuristic is introduced that automatically triggers this optimization when the build generates 3 or more lazy chunks. Developers can customize this behavior or disable it entirely using the NG_BUILD_OPTIMIZE_CHUNKS environment variable. Setting it to a number adjusts the threshold of lazy chunks required to trigger optimization, while setting it to false disables the feature if issues arise in specific projects.

Author: clydin

packages/angular/build/src/builders/application/chunk-optimizer.ts

@@ -19,16 +19,17 @@
 
 import type { Message, Metafile } from 'esbuild';
 import assert from 'node:assert';
-import { rollup } from 'rollup';
-import { useRolldownChunks } from '../../utils/environment-options';
+import { type Plugin, rollup } from 'rollup';
 import {
   BuildOutputFile,
   BuildOutputFileType,
   BundleContextResult,
   InitialFileRecord,
 } from '../../tools/esbuild/bundler-context';
 import { createOutputFile } from '../../tools/esbuild/utils';
+import { useRolldownChunks } from '../../utils/environment-options';
 import { assertIsError } from '../../utils/error';
+import { toPosixPath } from '../../utils/path';
 
 /**
  * Represents a minimal subset of a Rollup/Rolldown output asset.
@@ -137,15 +138,23 @@ function bundleOutputToEsbuildMetafile(
       ...(chunk.dynamicImports?.map((path) => ({ path, kind: 'dynamic-import' as const })) ?? []),
     ];
 
+    let entryPoint: string | undefined;
+    if (chunk.facadeModuleId) {
+      const posixFacadeModuleId = toPosixPath(chunk.facadeModuleId);
+      for (const [outputPath, output] of Object.entries(originalMetafile.outputs)) {
+        if (posixFacadeModuleId.endsWith(outputPath)) {
+          entryPoint = output.entryPoint;
+          break;
+        }
+      }
+    }
+
     newMetafile.outputs[chunk.fileName] = {
       bytes: Buffer.byteLength(chunk.code, 'utf8'),
       inputs: newOutputInputs,
       imports,
       exports: chunk.exports ?? [],
-      entryPoint:
-        chunk.isEntry && chunk.facadeModuleId
-          ? originalMetafile.outputs[chunk.facadeModuleId]?.entryPoint
-          : undefined,
+      entryPoint,
     };
   }
 
@@ -201,6 +210,7 @@ function createChunkOptimizationFailureMessage(message: string): Message {
  * @param sourcemap A boolean or 'hidden' to control sourcemap generation.
  * @returns A promise that resolves to the updated build result with optimized chunks.
  */
+// eslint-disable-next-line max-lines-per-function
 export async function optimizeChunks(
   original: BundleContextResult,
   sourcemap: boolean | 'hidden',
@@ -291,18 +301,20 @@ export async function optimizeChunks(
       const result = await bundle.generate({
         minify: { mangle: false, compress: false },
         sourcemap,
-        chunkFileNames: (chunkInfo) => `${chunkInfo.name.replace(/-[a-zA-Z0-9]{8}$/, '')}-[hash].js`,
+        chunkFileNames: (chunkInfo) =>
+          `${chunkInfo.name.replace(/-[a-zA-Z0-9]{8}$/, '')}-[hash].js`,
       });
       optimizedOutput = result.output;
     } else {
       bundle = await rollup({
         input: mainFile,
-        plugins: plugins as any,
+        plugins: plugins as Plugin[],
       });
 
       const result = await bundle.generate({
         sourcemap,
-        chunkFileNames: (chunkInfo) => `${chunkInfo.name.replace(/-[a-zA-Z0-9]{8}$/, '')}-[hash].js`,
+        chunkFileNames: (chunkInfo) =>
+          `${chunkInfo.name.replace(/-[a-zA-Z0-9]{8}$/, '')}-[hash].js`,
       });
       optimizedOutput = result.output;
     }

packages/angular/build/src/builders/application/execute-build.ts

@@ -25,7 +25,7 @@ import {
   transformSupportedBrowsersToTargets,
 } from '../../tools/esbuild/utils';
 import { BudgetCalculatorResult, checkBudgets } from '../../utils/bundle-calculator';
-import { shouldOptimizeChunks } from '../../utils/environment-options';
+import { optimizeChunksThreshold } from '../../utils/environment-options';
 import { resolveAssets } from '../../utils/resolve-assets';
 import {
   SERVER_APP_ENGINE_MANIFEST_FILENAME,
@@ -131,16 +131,6 @@ export async function executeBuild(
     bundlingResult = BundlerContext.mergeResults([bundlingResult, ...componentResults]);
   }
 
-  if (options.optimizationOptions.scripts && shouldOptimizeChunks) {
-    const { optimizeChunks } = await import('./chunk-optimizer');
-    bundlingResult = await profileAsync('OPTIMIZE_CHUNKS', () =>
-      optimizeChunks(
-        bundlingResult,
-        options.sourcemapOptions.scripts ? !options.sourcemapOptions.hidden || 'hidden' : false,
-      ),
-    );
-  }
-
   const executionResult = new ExecutionResult(
     bundlerContexts,
     componentStyleBundler,
@@ -161,6 +151,37 @@ export async function executeBuild(
     return executionResult;
   }
 
+  // Optimize chunks if enabled and threshold is met.
+  // This pass uses Rollup/Rolldown to further optimize chunks generated by esbuild.
+  if (options.optimizationOptions.scripts) {
+    // Count lazy chunks (files not needed for initial load).
+    // Advanced chunk optimization is most beneficial when there are multiple lazy chunks.
+    const { metafile, initialFiles } = bundlingResult;
+    const lazyChunksCount = Object.keys(metafile.outputs).filter(
+      (path) => path.endsWith('.js') && !initialFiles.has(path),
+    ).length;
+
+    // Only run if the number of lazy chunks meets the configured threshold.
+    // This avoids overhead for small projects with few chunks.
+    if (lazyChunksCount >= optimizeChunksThreshold) {
+      const { optimizeChunks } = await import('./chunk-optimizer');
+      const optimizationResult = await profileAsync('OPTIMIZE_CHUNKS', () =>
+        optimizeChunks(
+          bundlingResult,
+          options.sourcemapOptions.scripts ? !options.sourcemapOptions.hidden || 'hidden' : false,
+        ),
+      );
+
+      if (optimizationResult.errors) {
+        executionResult.addErrors(optimizationResult.errors);
+
+        return executionResult;
+      }
+
+      bundlingResult = optimizationResult;
+    }
+  }
+
   // Analyze external imports if external options are enabled
   if (options.externalPackages || bundlingResult.externalConfiguration) {
     const {

packages/angular/build/src/builders/unit-test/runners/vitest/plugins.ts

@@ -12,12 +12,6 @@ import { createRequire } from 'node:module';
 import { platform } from 'node:os';
 import path from 'node:path';
 
-interface ExistingRawSourceMap {
-  sources?: string[];
-  sourcesContent?: string[];
-  mappings?: string;
-}
-
 import type {
   BrowserConfigOptions,
   InlineConfig,
@@ -30,6 +24,12 @@ import { toPosixPath } from '../../../../utils/path';
 import type { ResultFile } from '../../../application/results';
 import type { NormalizedUnitTestBuilderOptions } from '../../options';
 
+interface ExistingRawSourceMap {
+  sources?: string[];
+  sourcesContent?: string[];
+  mappings?: string;
+}
+
 type VitestPlugins = Awaited<ReturnType<typeof VitestPlugin>>;
 
 interface PluginOptions {

packages/angular/build/src/utils/environment-options.ts

@@ -155,7 +155,29 @@ export const useJSONBuildLogs = parseTristate(process.env['NG_BUILD_LOGS_JSON'])
 /**
  * When `NG_BUILD_OPTIMIZE_CHUNKS` is enabled, the build will optimize chunks.
  */
-export const shouldOptimizeChunks = parseTristate(process.env['NG_BUILD_OPTIMIZE_CHUNKS']) === true;
+/**
+ * The threshold of lazy chunks required to enable the chunk optimization pass.
+ * Can be configured via the `NG_BUILD_OPTIMIZE_CHUNKS` environment variable.
+ * - `false` or `0` disables the feature.
+ * - `true` or `1` forces the feature on (threshold 0).
+ * - A number sets the specific threshold.
+ * - Default is 3.
+ */
+const optimizeChunksEnv = process.env['NG_BUILD_OPTIMIZE_CHUNKS'];
+export const optimizeChunksThreshold = (() => {
+  if (optimizeChunksEnv === undefined) {
+    return 3;
+  }
+  if (optimizeChunksEnv === 'false' || optimizeChunksEnv === '0') {
+    return Infinity;
+  }
+  if (optimizeChunksEnv === 'true' || optimizeChunksEnv === '1') {
+    return 0;
+  }
+  const num = Number.parseInt(optimizeChunksEnv, 10);
+
+  return Number.isNaN(num) || num < 0 ? 3 : num;
+})();
 
 /**
  * When `NG_HMR_CSTYLES` is enabled, component styles will be hot-reloaded.

packages/angular/build/src/utils/server-rendering/manifest.ts

@@ -12,7 +12,6 @@ import { runInThisContext } from 'node:vm';
 import { NormalizedApplicationBuildOptions } from '../../builders/application/options';
 import { type BuildOutputFile, BuildOutputFileType } from '../../tools/esbuild/bundler-context';
 import { createOutputFile } from '../../tools/esbuild/utils';
-import { shouldOptimizeChunks } from '../environment-options';
 
 export const SERVER_APP_MANIFEST_FILENAME = 'angular-app-manifest.mjs';
 export const SERVER_APP_ENGINE_MANIFEST_FILENAME = 'angular-app-engine-manifest.mjs';
@@ -168,11 +167,9 @@ export function generateAngularServerAppManifest(
   }
 
   // When routes have been extracted, mappings are no longer needed, as preloads will be included in the metadata.
-  // When shouldOptimizeChunks is enabled the metadata is no longer correct and thus we cannot generate the mappings.
-  const entryPointToBrowserMapping =
-    routes?.length || shouldOptimizeChunks
-      ? undefined
-      : generateLazyLoadedFilesMappings(metafile, initialFiles, publicPath);
+  const entryPointToBrowserMapping = routes?.length
+    ? undefined
+    : generateLazyLoadedFilesMappings(metafile, initialFiles, publicPath);
 
   const manifestContent = `
 export default {

tests/e2e.bzl

@@ -57,6 +57,8 @@ WEBPACK_IGNORE_TESTS = [
     "tests/build/incremental-watch.js",
     "tests/build/chunk-optimizer.js",
     "tests/build/chunk-optimizer-lazy.js",
+    "tests/build/chunk-optimizer-heuristic.js",
+    "tests/build/chunk-optimizer-env.js",
 ]
 
 def _to_glob(patterns):

tests/e2e/tests/build/chunk-optimizer-env.ts

@@ -0,0 +1,109 @@
+import assert from 'node:assert/strict';
+import { readdir } from 'node:fs/promises';
+import { replaceInFile } from '../../utils/fs';
+import { execWithEnv, ng } from '../../utils/process';
+import { installPackage, uninstallPackage } from '../../utils/packages';
+
+export default async function () {
+  // Case 1: Force on with true/1 with 1 lazy chunk
+  await ng('generate', 'component', 'lazy-a');
+  await replaceInFile(
+    'src/app/app.routes.ts',
+    'routes: Routes = [];',
+    `routes: Routes = [
+      {
+        path: 'lazy-a',
+        loadComponent: () => import('./lazy-a/lazy-a').then(m => m.LazyA),
+      },
+    ];`,
+  );
+
+  // Build with forced optimization
+  await execWithEnv('ng', ['build', '--output-hashing=none'], {
+    ...process.env,
+    NG_BUILD_OPTIMIZE_CHUNKS: 'true',
+  });
+  const files1Opt = await readdir('dist/test-project/browser');
+  const jsFiles1Opt = files1Opt.filter((f) => f.endsWith('.js'));
+
+  // Build with forced off
+  await execWithEnv('ng', ['build', '--output-hashing=none'], {
+    ...process.env,
+    NG_BUILD_OPTIMIZE_CHUNKS: 'false',
+  });
+  const files1Unopt = await readdir('dist/test-project/browser');
+  const jsFiles1Unopt = files1Unopt.filter((f) => f.endsWith('.js'));
+
+  // We just verify it runs without error.
+  // With 1 chunk it might not be able to optimize further, so counts might be equal.
+
+  // Case 2: Force off with false/0 with 3 lazy chunks
+  await ng('generate', 'component', 'lazy-b');
+  await ng('generate', 'component', 'lazy-c');
+  await replaceInFile(
+    'src/app/app.routes.ts',
+    `path: 'lazy-a',
+        loadComponent: () => import('./lazy-a/lazy-a').then(m => m.LazyA),
+      },`,
+    `path: 'lazy-a',
+        loadComponent: () => import('./lazy-a/lazy-a').then(m => m.LazyA),
+      },
+      {
+        path: 'lazy-b',
+        loadComponent: () => import('./lazy-b/lazy-b').then(m => m.LazyB),
+      },
+      {
+        path: 'lazy-c',
+        loadComponent: () => import('./lazy-c/lazy-c').then(m => m.LazyC),
+      },`,
+  );
+
+  // Build with forced off
+  await execWithEnv('ng', ['build', '--output-hashing=none'], {
+    ...process.env,
+    NG_BUILD_OPTIMIZE_CHUNKS: 'false',
+  });
+  const files3Unopt = await readdir('dist/test-project/browser');
+  const jsFiles3Unopt = files3Unopt.filter((f) => f.endsWith('.js'));
+
+  // Build with default (should optimize because 3 chunks)
+  await ng('build', '--output-hashing=none');
+  const files3Default = await readdir('dist/test-project/browser');
+  const jsFiles3Default = files3Default.filter((f) => f.endsWith('.js'));
+
+  assert.ok(
+    jsFiles3Default.length < jsFiles3Unopt.length,
+    `Expected default build (3 chunks) to be optimized compared to forced off. Default: ${jsFiles3Default.length}, Forced Off: ${jsFiles3Unopt.length}`,
+  );
+
+  // Case 3: Custom threshold
+  // Set threshold to 4 with 3 chunks -> should NOT optimize!
+  await execWithEnv('ng', ['build', '--output-hashing=none'], {
+    ...process.env,
+    NG_BUILD_OPTIMIZE_CHUNKS: '4',
+  });
+  const files3Thresh4 = await readdir('dist/test-project/browser');
+  const jsFiles3Thresh4 = files3Thresh4.filter((f) => f.endsWith('.js'));
+
+  assert.ok(
+    jsFiles3Thresh4.length >= jsFiles3Unopt.length,
+    `Expected build with threshold 4 and 3 chunks to NOT be optimized. Thresh 4: ${jsFiles3Thresh4.length}, Unoptimized: ${jsFiles3Unopt.length}`,
+  );
+
+  // Case 4: Opt into Rolldown
+  await installPackage('rolldown@1.0.0-rc.12');
+  try {
+    await execWithEnv('ng', ['build', '--output-hashing=none'], {
+      ...process.env,
+      NG_BUILD_CHUNKS_ROLLDOWN: '1',
+      NG_BUILD_OPTIMIZE_CHUNKS: 'true',
+    });
+    const filesRolldown = await readdir('dist/test-project/browser');
+    const jsFilesRolldown = filesRolldown.filter((f) => f.endsWith('.js'));
+
+    assert.ok(jsFilesRolldown.length > 0, 'Expected Rolldown build to produce output files.');
+  } finally {
+    // Clean up
+    await uninstallPackage('rolldown');
+  }
+}