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 output of Object.values(originalMetafile.outputs)) {
+        if (output.entryPoint && posixFacadeModuleId.endsWith(output.entryPoint)) {
+          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,
@@ -149,6 +139,8 @@ export async function executeBuild(
   );
   executionResult.addWarnings(bundlingResult.warnings);
 
+  let chunksOptimized = false;
+
   // Add used external component style referenced files to be watched
   if (options.externalRuntimeStyles) {
     executionResult.extraWatchFiles.push(...componentStyleBundler.collectReferencedFiles());
@@ -161,6 +153,39 @@ 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;
+      }
+
+      chunksOptimized = true;
+
+      bundlingResult = optimizationResult;
+    }
+  }
+
   // Analyze external imports if external options are enabled
   if (options.externalPackages || bundlingResult.externalConfiguration) {
     const {
@@ -271,7 +296,13 @@ export async function executeBuild(
 
   // Perform i18n translation inlining if enabled
   if (i18nOptions.shouldInline) {
-    const result = await inlineI18n(metafile, options, executionResult, initialFiles);
+    const result = await inlineI18n(
+      metafile,
+      options,
+      executionResult,
+      initialFiles,
+      chunksOptimized,
+    );
     executionResult.addErrors(result.errors);
     executionResult.addWarnings(result.warnings);
     executionResult.addPrerenderedRoutes(result.prerenderedRoutes);
@@ -284,6 +315,7 @@ export async function executeBuild(
       initialFiles,
       // Set lang attribute to the defined source locale if present
       i18nOptions.hasDefinedSourceLocale ? i18nOptions.sourceLocale : undefined,
+      chunksOptimized,
     );
 
     // Deduplicate and add errors and warnings

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

@@ -50,6 +50,7 @@ export async function executePostBundleSteps(
   assetFiles: BuildOutputAsset[],
   initialFiles: Map<string, InitialFileRecord>,
   locale: string | undefined,
+  chunksOptimized: boolean,
 ): Promise<{
   errors: string[];
   warnings: string[];
@@ -124,6 +125,7 @@ export async function executePostBundleSteps(
       initialFilesPaths,
       metafile,
       publicPath,
+      chunksOptimized,
     );
 
     additionalOutputFiles.push(
@@ -207,6 +209,7 @@ export async function executePostBundleSteps(
         initialFilesPaths,
         metafile,
         publicPath,
+        chunksOptimized,
       );
 
       for (const chunk of serverAssetsChunks) {

packages/angular/build/src/builders/application/i18n.ts

@@ -34,6 +34,7 @@ export async function inlineI18n(
   options: NormalizedApplicationBuildOptions,
   executionResult: ExecutionResult,
   initialFiles: Map<string, InitialFileRecord>,
+  chunksOptimized: boolean,
 ): Promise<{
   errors: string[];
   warnings: string[];
@@ -97,6 +98,7 @@ export async function inlineI18n(
         executionResult.assetFiles,
         initialFiles,
         locale,
+        chunksOptimized,
       );
 
       localeOutputFiles.push(...additionalOutputFiles);

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) ? 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';
@@ -137,6 +136,7 @@ export function generateAngularServerAppManifest(
   initialFiles: Set<string>,
   metafile: Metafile,
   publicPath: string | undefined,
+  chunksOptimized: boolean,
 ): {
   manifestContent: string;
   serverAssetsChunks: BuildOutputFile[];
@@ -168,11 +168,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):