fix(@angular/build): conditionally declare tslib in built library package

Inspects Rolldown output chunk imports to detect whether any generated library bundle imports `tslib` (for example, when custom decorators or explicit resource management helpers are emitted). When `tslib` is imported and not already declared in the library's `package.json` `dependencies`, resolves the `tslib` version range from `@angular/compiler` (with fallback to `tslib/package.json`) and adds it to the emitted `package.json`.

Closes #34131

Author: alan-agius4

packages/angular/build/src/builders/library/builder.ts

@@ -8,7 +8,6 @@
 
 import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
 import type { logging } from '@angular-devkit/core';
-import fs from 'node:fs/promises';
 import {
   resetSassWorkerPoolCaches,
   shutdownSassWorkerPool,
@@ -27,8 +26,9 @@ import type { BuildWatcher } from '../../utils/watcher';
 import { normalizeLibraryOptions } from './options';
 import { updateWatchedEntryPoints } from './pipeline/entry-points';
 import type { createComponentStylesheetBundlerForLibrary } from './pipeline/stylesheet-bundler';
+import { loadPackageJson } from './pipeline/utils';
 import type { Schema as LibraryBuilderOptions } from './schema';
-import type { NormalizedLibraryOptions, PackageJsonData, SingleBuildState } from './types';
+import type { NormalizedLibraryOptions, SingleBuildState } from './types';
 
 /**
  * Executes the library builder to compile, bundle, and package an Angular library into the Angular Package Format (APF).
@@ -340,15 +340,6 @@ async function* runWatchLoop(
   }
 }
 
-/**
- * Loads and parses a JSON file from disk.
- */
-async function loadPackageJson(packageJsonPath: string): Promise<PackageJsonData> {
-  const content = await fs.readFile(packageJsonPath, 'utf-8');
-
-  return JSON.parse(content) as PackageJsonData;
-}
-
 /**
  * Logs the build completion time and status.
  */

packages/angular/build/src/builders/library/options.ts

@@ -7,7 +7,6 @@
  */
 
 import type { BuilderContext } from '@angular-devkit/architect';
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { StylesheetPluginsass } from '../../tools/esbuild/stylesheets/stylesheet-plugin-factory';
 import { normalizeAssetPatterns } from '../../utils';
@@ -21,6 +20,7 @@ import {
 } from '../../utils/postcss-configuration';
 import { getProjectRootPaths } from '../../utils/project-metadata';
 import { normalizeEntryPoints } from './pipeline/entry-points';
+import { loadPackageJson } from './pipeline/utils';
 import type { Schema as LibraryBuilderOptions } from './schema';
 import type { NormalizedLibraryOptions, PackageJsonData } from './types';
 
@@ -55,8 +55,7 @@ export async function normalizeLibraryOptions(
 
   let packageJson: PackageJsonData;
   try {
-    const packageJsonContent = await fs.readFile(packageJsonPath, 'utf8');
-    packageJson = JSON.parse(packageJsonContent) as PackageJsonData;
+    packageJson = await loadPackageJson(packageJsonPath);
   } catch (error) {
     assertIsError(error);
     throw new Error(`Failed to read 'package.json' at '${packageJsonPath}': ${error.message}`, {

packages/angular/build/src/builders/library/pipeline/build-action.ts

@@ -193,8 +193,16 @@ export async function buildAction(actionContext: BuildActionContext): Promise<vo
     }
   }
 
-  if (shouldGenerateManifests) {
-    filesToEmit.push(...generatePackageManifests(options, isWatchMode));
+  let hasTslibImport = false;
+  for (const entryPoint of options.entryPoints.values()) {
+    if (buildState.previousBundleResults.get(entryPoint.name)?.hasTslibImport) {
+      hasTslibImport = true;
+      break;
+    }
+  }
+
+  if (shouldGenerateManifests || buildState.hasEmittedTslib !== hasTslibImport) {
+    filesToEmit.push(...(await generatePackageManifests(options, isWatchMode, hasTslibImport)));
   }
 
   const resolvedAssetsToEmit = (actionContext.assetsToEmit ??= await collectAssetsToEmit(
@@ -220,6 +228,7 @@ export async function buildAction(actionContext: BuildActionContext): Promise<vo
   });
 
   buildState.hasEmittedManifests = true;
+  buildState.hasEmittedTslib = hasTslibImport;
   buildState.hasEmittedAssets = true;
 }
 

packages/angular/build/src/builders/library/pipeline/bundler.ts

@@ -69,6 +69,9 @@ interface MultiBundleOutput {
   /** Map of bundle entry names to the set of virtual module IDs included in the bundle. */
   moduleIdsByBundle: Map<string, Set<string>>;
 
+  /** Set of bundle entry names that import 'tslib'. */
+  tslibBundles: Set<string>;
+
   /** Warning messages emitted during the bundle invocation. */
   warnings: string[];
 }
@@ -113,15 +116,16 @@ export async function bundleEntryPoints(
 
   for (const { entryPoint, previousBundleResult } of items) {
     const { bundleName, name } = entryPoint;
+    const esmModuleIds = esmOutput.moduleIdsByBundle.get(bundleName);
     bundleResults.set(name, {
-      esmModuleIds:
-        esmOutput.moduleIdsByBundle.get(bundleName) ??
-        previousBundleResult?.esmModuleIds ??
-        new Set(),
+      esmModuleIds: esmModuleIds ?? previousBundleResult?.esmModuleIds ?? new Set(),
       dtsModuleIds:
         dtsOutput.moduleIdsByBundle.get(bundleName) ??
         previousBundleResult?.dtsModuleIds ??
         new Set(),
+      hasTslibImport: esmModuleIds
+        ? esmOutput.tslibBundles.has(bundleName)
+        : (previousBundleResult?.hasTslibImport ?? false),
     });
   }
 
@@ -238,9 +242,10 @@ function createMemoryFileLoaderPlugin(
 function processRolldownOutput(
   output: RolldownOutput['output'],
   dir: string,
-): Pick<MultiBundleOutput, 'filesToEmit' | 'moduleIdsByBundle'> {
+): Omit<MultiBundleOutput, 'warnings'> {
   const filesToEmit: MemoryOutputFile[] = [];
   const moduleIdsByBundle = new Map<string, Set<string>>();
+  const tslibBundles = new Set<string>();
   const chunksByFileName = new Map<string, OutputChunk>();
   const entryChunks: OutputChunk[] = [];
 
@@ -286,6 +291,10 @@ function processRolldownOutput(
       }
 
       for (const depFile of [...chunk.imports, ...chunk.dynamicImports]) {
+        if (depFile === 'tslib') {
+          tslibBundles.add(entryChunk.name);
+        }
+
         const depChunk = chunksByFileName.get(depFile);
         if (depChunk && !visited.has(depChunk)) {
           queue.push(depChunk);
@@ -294,7 +303,7 @@ function processRolldownOutput(
     }
   }
 
-  return { filesToEmit, moduleIdsByBundle };
+  return { filesToEmit, moduleIdsByBundle, tslibBundles };
 }
 
 /**
@@ -380,7 +389,12 @@ async function bundleAllEsm(
   options: NormalizedLibraryOptions,
 ): Promise<MultiBundleOutput> {
   if (entryPoints.length === 0) {
-    return { filesToEmit: [], moduleIdsByBundle: new Map(), warnings: [] };
+    return {
+      filesToEmit: [],
+      moduleIdsByBundle: new Map(),
+      tslibBundles: new Set(),
+      warnings: [],
+    };
   }
 
   return executeMultiBundle(
@@ -405,7 +419,12 @@ async function bundleAllDts(
   options: NormalizedLibraryOptions,
 ): Promise<MultiBundleOutput> {
   if (entryPoints.length === 0) {
-    return { filesToEmit: [], moduleIdsByBundle: new Map(), warnings: [] };
+    return {
+      filesToEmit: [],
+      moduleIdsByBundle: new Map(),
+      tslibBundles: new Set(),
+      warnings: [],
+    };
   }
 
   const dtsSourcemap = options.declarationMap;

packages/angular/build/src/builders/library/pipeline/package-manifests.ts

@@ -6,26 +6,30 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import type { NormalizedLibraryOptions, PackageJsonData } from '../types';
 import {
   FESM_OUTPUT_DIR,
   type MemoryOutputFile,
   TYPES_OUTPUT_DIR,
   createMemoryOutputFile,
+  loadPackageJson,
 } from './utils';
 
 /**
  * Generates the APF package.json and secondary entry point package.json manifests.
  *
  * @param options The normalized library options.
  * @param isWatchMode Whether the builder is running in watch mode.
+ * @param hasTslibImport Whether any output chunk imports 'tslib'.
  * @returns An array of memory output files containing generated package manifests and .npmignore.
  */
-export function generatePackageManifests(
+export async function generatePackageManifests(
   options: NormalizedLibraryOptions,
   isWatchMode: boolean,
-): MemoryOutputFile[] {
+  hasTslibImport = false,
+): Promise<MemoryOutputFile[]> {
   const { packageJson: rawPackageJson, keepLifecycleScripts, compilationMode } = options;
 
   const {
@@ -73,6 +77,16 @@ export function generatePackageManifests(
     version: isWatchMode ? `0.0.0-watch+${Date.now()}` : version,
   };
 
+  if (hasTslibImport && !rawPackageJson.dependencies?.['tslib']) {
+    const tslibVersion = await getAngularTslibRange(options.workspaceRoot);
+    if (tslibVersion) {
+      distPackageJson.dependencies = {
+        ...rawPackageJson.dependencies,
+        tslib: tslibVersion,
+      };
+    }
+  }
+
   // Retain scripts if keepLifecycleScripts is set
   if (keepLifecycleScripts && scripts) {
     distPackageJson.scripts = scripts;
@@ -166,3 +180,46 @@ function createExportConditions(
     default: fesmPath,
   };
 }
+
+/**
+ * Cached tslib range used by the Angular compiler.
+ */
+let cachedTslibRange: string | undefined;
+
+/**
+ * Get the tslib range used by the Angular compiler.
+ * @param workspaceRoot path to the workspace root
+ * @returns tslib range
+ */
+async function getAngularTslibRange(workspaceRoot: string): Promise<string> {
+  if (cachedTslibRange) {
+    return cachedTslibRange;
+  }
+
+  const workspaceRequire = createRequire(path.join(workspaceRoot, 'package.json'));
+
+  // Try resolving via @angular/compiler dependencies
+  try {
+    const angularCompilerPkg = await loadPackageJson(
+      workspaceRequire.resolve('@angular/compiler/package.json'),
+    );
+    cachedTslibRange = angularCompilerPkg.dependencies?.['tslib'];
+  } catch {}
+
+  // Fallback: Try resolving tslib directly
+  if (!cachedTslibRange) {
+    try {
+      const tslibPkg = await loadPackageJson(workspaceRequire.resolve('tslib/package.json'));
+      if (tslibPkg.version) {
+        cachedTslibRange = `^${tslibPkg.version}`;
+      }
+    } catch {}
+  }
+
+  // Fail fast if still unresolved
+  if (!cachedTslibRange) {
+    throw new Error('Unable to resolve tslib range.');
+  }
+
+  return cachedTslibRange;
+}