fix(@angular/build): support incremental asset updates and output cleanup in library watch mode

Ensure the library builder properly handles created, modified, and deleted assets during watch mode rebuilds, and removes stale bundle and manifest output files when entry points or exports change. Also normalize paths across the library builder pipeline to POSIX format.

Author: alan-agius4

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

@@ -24,7 +24,12 @@ import { getSupportedBrowsers } from '../../utils/supported-browsers';
 import { assertCompatibleAngularVersion } from '../../utils/version';
 import type { BuildWatcher } from '../../utils/watcher';
 import { normalizeLibraryOptions } from './options';
-import type { BuildActionResult } from './pipeline/build-action';
+import type {
+  BuildActionContext,
+  BuildActionResult,
+  buildAction,
+  hasModifiedWatchedFile,
+} from './pipeline/build-action';
 import { updateWatchedEntryPoints } from './pipeline/entry-points';
 import type { createComponentStylesheetBundlerForLibrary } from './pipeline/stylesheet-bundler';
 import { loadPackageJson } from './pipeline/utils';
@@ -111,13 +116,10 @@ export async function* executeLibraryBuilder(
     );
 
     // Track all referenced compilation files for watch mode
-    const watchedCompilationFiles = new Set<string>([
-      toPosixPath(tsConfigPath),
-      toPosixPath(packageJsonPath),
-    ]);
+    const watchedCompilationFiles = new Set<string>([tsConfigPath, packageJsonPath]);
 
     for (const entryPoint of normalizedOptions.entryPoints.values()) {
-      watchedCompilationFiles.add(toPosixPath(entryPoint.entryFilePath));
+      watchedCompilationFiles.add(entryPoint.entryFilePath);
     }
 
     if (isWatchMode) {
@@ -130,7 +132,10 @@ export async function* executeLibraryBuilder(
         poll,
         preserveSymlinks,
         signal,
-        watchFiles: watchedCompilationFiles,
+        watchFiles: [
+          ...watchedCompilationFiles,
+          ...normalizedOptions.assets.map((asset) => asset.input),
+        ],
       });
 
       context.addTeardown?.(() => void watcher?.close());
@@ -194,21 +199,21 @@ export async function* executeLibraryBuilder(
  * @param actionContext The build action context and state.
  * @param withProgress Progress wrapper function (`withSpinner` or `withNoProgress`).
  * @param watcher Optional file watcher for watch mode.
- * @param buildAction The library build action function to execute.
+ * @param buildActionFn The library build action function to execute.
  * @returns A promise resolving to the Architect `BuilderOutput`.
  */
 async function executeBuild(
   message: string,
-  actionContext: import('./pipeline/build-action').BuildActionContext,
+  actionContext: BuildActionContext,
   withProgress: typeof withSpinner,
   watcher: BuildWatcher | undefined,
-  buildAction: typeof import('./pipeline/build-action').buildAction,
+  buildActionFn: typeof buildAction,
 ): Promise<BuilderOutput> {
   const startTime = process.hrtime.bigint();
   const { context, watchedCompilationFiles, isWatchMode, options } = actionContext;
 
   try {
-    const result = await withProgress(message, () => buildAction(actionContext));
+    const result = await withProgress(message, () => buildActionFn(actionContext));
     logMessages(context.logger, result);
 
     const success = result.errors.length === 0;
@@ -227,16 +232,27 @@ async function executeBuild(
     if (watcher) {
       watcher.add(Array.from(watchedCompilationFiles));
 
-      const { assetsToEmit } = actionContext;
-      if (assetsToEmit?.length) {
-        watcher.add(assetsToEmit.map((asset) => asset.source));
+      const { collectedAssets } = actionContext;
+      if (collectedAssets?.filesToEmit.length) {
+        watcher.add(collectedAssets.filesToEmit.map((asset) => asset.source));
       }
     }
   }
 }
 
 /**
  * Runs the watch loop, rebuilding the library as watched files are modified.
+ *
+ * @param watcher The file watcher instance.
+ * @param options The normalized library builder options with POSIX paths.
+ * @param stylesheetBundler The component stylesheet bundler instance.
+ * @param watchedCompilationFiles Set of POSIX file paths tracked for compilation.
+ * @param context The Architect builder context.
+ * @param withProgress Progress wrapper function (`withSpinner` or `withNoProgress`).
+ * @param buildState The state preserved across incremental builds.
+ * @param buildActionFn The library build action function to execute.
+ * @param hasModifiedWatchedFileFn Helper to check whether watched compilation files changed.
+ * @param signal Optional abort signal to terminate the watch loop.
  */
 async function* runWatchLoop(
   watcher: BuildWatcher,
@@ -246,14 +262,13 @@ async function* runWatchLoop(
   context: BuilderContext,
   withProgress: typeof withSpinner,
   buildState: SingleBuildState,
-  buildAction: typeof import('./pipeline/build-action').buildAction,
-  hasModifiedWatchedFile: typeof import('./pipeline/build-action').hasModifiedWatchedFile,
+  buildActionFn: typeof buildAction,
+  hasModifiedWatchedFileFn: typeof hasModifiedWatchedFile,
   signal?: AbortSignal,
 ): AsyncIterableIterator<BuilderOutput> {
   const { collectAssetsToEmit } = await import('./pipeline/assets');
 
   const { workspaceRoot, packageJsonPath, assets, clearScreen } = options;
-  const posixPackageJsonPath = toPosixPath(packageJsonPath);
 
   for await (const changes of watcher) {
     if (signal?.aborted) {
@@ -293,13 +308,13 @@ async function* runWatchLoop(
 
     // Check if package.json was modified
     let hasPackageJsonChanges = false;
-    if (changedFiles.has(posixPackageJsonPath)) {
+    if (changedFiles.has(packageJsonPath)) {
       try {
         const packageJson = await loadPackageJson(packageJsonPath);
-        options.packageJson = packageJson;
         if (!packageJson.name) {
           throw new Error(`The package.json at '${packageJsonPath}' must contain a 'name'.`);
         }
+        options.packageJson = packageJson;
         options.packageName = packageJson.name;
 
         updateWatchedEntryPoints(
@@ -328,15 +343,21 @@ async function* runWatchLoop(
       !buildState.singleProgramCache ||
       buildState.hasCompilationError ||
       buildState.hasEntryPointsChanges ||
-      hasModifiedWatchedFile(changedFiles, watchedCompilationFiles, posixPackageJsonPath);
+      hasModifiedWatchedFileFn(changedFiles, watchedCompilationFiles, packageJsonPath);
 
-    const assetsToEmit = await collectAssetsToEmit(
+    const collectedAssets = await collectAssetsToEmit(
       assets,
       workspaceRoot,
       buildState.hasEmittedAssets ? changedFiles : undefined,
+      buildState.emittedAssets,
     );
 
-    if (!hasSourceChanges && !hasPackageJsonChanges && assetsToEmit.length === 0) {
+    if (
+      !hasSourceChanges &&
+      !hasPackageJsonChanges &&
+      collectedAssets.filesToEmit.length === 0 &&
+      collectedAssets.filesToDelete.length === 0
+    ) {
       continue;
     }
 
@@ -350,11 +371,11 @@ async function* runWatchLoop(
         context,
         buildState,
         modifiedFiles: changedFiles,
-        assetsToEmit,
+        collectedAssets,
       },
       withProgress,
       watcher,
-      buildAction,
+      buildActionFn,
     );
   }
 }
@@ -388,7 +409,7 @@ function logMessages(
  * @param logger The Architect logger API.
  * @param startTime High-resolution timestamp recorded when the build iteration started.
  * @param success Whether the build iteration succeeded without errors.
- * @param outputPath Optional output directory path to log on successful builds.
+ * @param outputPath Optional POSIX output directory path to log on successful builds.
  */
 function logBuildResult(
   logger: logging.LoggerApi,

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

@@ -13,6 +13,7 @@ import { normalizeAssetPatterns } from '../../utils';
 import { supportColor } from '../../utils/color';
 import { assertIsError } from '../../utils/error';
 import { normalizeCacheOptions } from '../../utils/normalize-cache';
+import { toPosixPath } from '../../utils/path';
 import {
   generateSearchDirectories,
   getTailwindConfig,
@@ -24,14 +25,25 @@ import { loadPackageJson } from './pipeline/utils';
 import type { Schema as LibraryBuilderOptions } from './schema';
 import type { NormalizedLibraryOptions, PackageJsonData } from './types';
 
+/**
+ * Normalizes raw library builder options into {@link NormalizedLibraryOptions} with all
+ * file and directory paths normalized to POSIX format.
+ *
+ * @param context The Architect builder context.
+ * @param projectName The name of the library project.
+ * @param options The raw library builder schema options.
+ * @returns A promise resolving to the normalized library options.
+ */
 export async function normalizeLibraryOptions(
   context: BuilderContext,
   projectName: string,
   options: LibraryBuilderOptions,
 ): Promise<NormalizedLibraryOptions> {
-  const { workspaceRoot } = context;
+  const workspaceRoot = toPosixPath(context.workspaceRoot);
   const projectMetadata = await context.getProjectMetadata(projectName);
-  const { projectRoot, projectSourceRoot } = getProjectRootPaths(workspaceRoot, projectMetadata);
+  const projectRootPaths = getProjectRootPaths(workspaceRoot, projectMetadata);
+  const projectRoot = toPosixPath(projectRootPaths.projectRoot);
+  const projectSourceRoot = toPosixPath(projectRootPaths.projectSourceRoot);
 
   const {
     tsConfig,
@@ -50,8 +62,8 @@ export async function normalizeLibraryOptions(
     clearScreen,
   } = options;
 
-  const resolvedTsConfigPath = path.resolve(workspaceRoot, tsConfig);
-  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const resolvedTsConfigPath = toPosixPath(path.resolve(workspaceRoot, tsConfig));
+  const packageJsonPath = path.posix.join(projectRoot, 'package.json');
 
   let packageJson: PackageJsonData;
   try {
@@ -99,7 +111,7 @@ export async function normalizeLibraryOptions(
     }
     defaultAssets.push({
       glob: 'README.md',
-      input: path.dirname(entryPoint.entryFilePath),
+      input: path.posix.dirname(entryPoint.entryFilePath),
       output: entryPoint.name,
     });
   }
@@ -109,7 +121,11 @@ export async function normalizeLibraryOptions(
     workspaceRoot,
     projectRoot,
     projectSourceRoot,
-  );
+  ).map((asset) => ({
+    ...asset,
+    input: toPosixPath(path.resolve(workspaceRoot, asset.input)),
+    output: toPosixPath(asset.output),
+  }));
 
   const cacheOptions = normalizeCacheOptions(
     projectMetadata,
@@ -119,7 +135,7 @@ export async function normalizeLibraryOptions(
   );
 
   const styleIncludePaths = (stylePreprocessorOptions?.includePaths ?? []).map((p: string) =>
-    path.resolve(workspaceRoot, p),
+    toPosixPath(path.resolve(workspaceRoot, p)),
   );
 
   const searchDirectories = await generateSearchDirectories([projectRoot, workspaceRoot]);
@@ -133,7 +149,9 @@ export async function normalizeLibraryOptions(
     projectRoot,
     packageName,
     packageJson,
-    outputPath: path.resolve(workspaceRoot, options.outputPath ?? path.join('dist', projectName)),
+    outputPath: toPosixPath(
+      path.resolve(workspaceRoot, options.outputPath ?? path.posix.join('dist', projectName)),
+    ),
     deleteOutputPath,
     packageJsonPath,
     tsConfigPath: resolvedTsConfigPath,