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,15 +19,15 @@
 
 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';
 
 /**
@@ -201,6 +201,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',
@@ -297,7 +298,7 @@ export async function optimizeChunks(
     } else {
       bundle = await rollup({
         input: mainFile,
-        plugins: plugins as any,
+        plugins: plugins as Plugin[],
       });
 
       const result = await bundle.generate({

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,7 @@ 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 +309,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,9 +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.
+  // When chunks are optimized the metadata is no longer correct and thus we cannot generate the mappings.
   const entryPointToBrowserMapping =
-    routes?.length || shouldOptimizeChunks
+    routes?.length || chunksOptimized
       ? undefined
       : generateLazyLoadedFilesMappings(metafile, initialFiles, publicPath);
 

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');
+  }
+}