fix(angular-rspack): handler accumulation and watchOptions for double rebuilds (#34154)

# Current Behavior
1. **Handler accumulation**: The `compilation`, `beforeCompile`, and
`done` hooks are registered inside `watchRun`, causing new handlers to
be added on every rebuild cycle. This leads to performance degradation
and duplicate operations during watch mode.
2. **Double rebuilds**: Rapid filesystem events (e.g., editor
backup/swap files) trigger multiple rebuilds because there's no
aggregation timeout configured.
3. **No watchOptions configuration**: Users cannot customize watcher
behavior (aggregateTimeout, ignored patterns, etc.).

# Expected Behavior
1. Hooks should be registered once outside of `watchRun` to prevent
accumulation. Shared state is used to pass data between watch cycles and
compilation hooks.
2. A default `aggregateTimeout: 50` batches rapid filesystem events to
prevent double rebuilds.
3. Users can provide custom `watchOptions` to configure watcher
behavior, with user options taking precedence over defaults.

# Related Issue(s)
#34142 (comment)

Author: faileon

packages/angular-rspack/src/lib/config/config-utils/common-config.ts

@@ -90,10 +90,14 @@ export async function getCommonConfig(
     },
     watch: normalizedOptions.watch,
     watchOptions: {
+      // Default aggregateTimeout to batch rapid filesystem events (e.g., editor backup files)
+      aggregateTimeout: 50,
       poll: normalizedOptions.poll,
       followSymlinks: normalizedOptions.preserveSymlinks,
       ignored:
         normalizedOptions.poll === undefined ? undefined : '**/node_modules/**',
+      // User-provided watchOptions take precedence
+      ...normalizedOptions.watchOptions,
     },
     ignoreWarnings: [
       // https://github.com/webpack-contrib/source-map-loader/blob/b2de4249c7431dd8432da607e08f0f65e9d64219/src/index.js#L83

packages/angular-rspack/src/lib/config/create-config.spec.ts

@@ -306,6 +306,55 @@ describe('createConfig', () => {
       ]);
     });
 
+    it('should set default watchOptions with aggregateTimeout of 50ms', async () => {
+      await expect(
+        createConfig({ options: configBase })
+      ).resolves.toStrictEqual([
+        expect.objectContaining({
+          watchOptions: expect.objectContaining({
+            aggregateTimeout: 50,
+          }),
+        }),
+      ]);
+    });
+
+    it('should allow overriding watchOptions.aggregateTimeout', async () => {
+      await expect(
+        createConfig({
+          options: {
+            ...configBase,
+            watchOptions: { aggregateTimeout: 200 },
+          },
+        })
+      ).resolves.toStrictEqual([
+        expect.objectContaining({
+          watchOptions: expect.objectContaining({
+            aggregateTimeout: 200,
+          }),
+        }),
+      ]);
+    });
+
+    it('should merge watchOptions with poll option', async () => {
+      await expect(
+        createConfig({
+          options: {
+            ...configBase,
+            poll: 1000,
+            watchOptions: { aggregateTimeout: 100 },
+          },
+        })
+      ).resolves.toStrictEqual([
+        expect.objectContaining({
+          watchOptions: expect.objectContaining({
+            aggregateTimeout: 100,
+            poll: 1000,
+            ignored: '**/node_modules/**',
+          }),
+        }),
+      ]);
+    });
+
     it.each([
       ['development', 'dev', true],
       ['production', 'prod', false],

packages/angular-rspack/src/lib/models/angular-rspack-plugin-options.ts

@@ -4,6 +4,7 @@ import type {
   StylePreprocessorOptions,
 } from '@nx/angular-rspack-compiler';
 import type { BudgetEntry } from '@angular/build/private';
+import type { WatchOptions } from '@rspack/core';
 import { I18nProjectMetadata } from './i18n';
 
 export interface DevServerOptions {
@@ -336,6 +337,11 @@ export interface AngularRspackPluginOptions {
    * Run build when files change.
    */
   watch?: boolean;
+  /**
+   * Options for the file watcher. Can be used to configure aggregateTimeout,
+   * ignored patterns, and other watcher behavior.
+   */
+  watchOptions?: WatchOptions;
   /**
    * @deprecated This is a no-op and can be safely removed.
    * The tsconfig file for web workers.
@@ -378,6 +384,11 @@ export interface NormalizedAngularRspackPluginOptions
   supportedBrowsers: string[];
   tsConfig: string;
   vendorChunk: boolean;
+  /**
+   * Adds more details to output logging.
+   */
+  verbose?: boolean;
   watch: boolean;
+  watchOptions?: WatchOptions;
   zoneless: boolean;
 }

packages/angular-rspack/src/lib/models/normalize-options.ts

@@ -277,6 +277,7 @@ export async function normalizeOptions(
     vendorChunk: options.vendorChunk ?? false,
     verbose: options.verbose ?? false,
     watch: options.watch ?? false,
+    watchOptions: options.watchOptions,
     zoneless,
   };
 }

packages/angular-rspack/src/lib/plugins/angular-rspack-plugin.ts

@@ -15,6 +15,7 @@ import {
 } from '@nx/angular-rspack-compiler';
 import { workspaceRoot } from '@nx/devkit';
 import {
+  type Compilation,
   type Compiler,
   type RspackOptionsNormalized,
   type RspackPluginInstance,
@@ -95,14 +96,21 @@ export class AngularRspackPlugin implements RspackPluginInstance {
       }
     );
 
+    let currentWatchingModifiedFiles = new Set<string>();
+    let watchRunInitialized = false;
+
+    // Register compilation hook once - adds modified files to dependencies
+    compiler.hooks.compilation.tap(PLUGIN_NAME + '_fileDeps', (compilation) => {
+      currentWatchingModifiedFiles.forEach((file) => {
+        compilation.fileDependencies.add(file);
+      });
+    });
+
     compiler.hooks.watchRun.tapAsync(
       PLUGIN_NAME,
       async (compiler, callback) => {
-        if (
-          !compiler.hooks.beforeCompile.taps.some(
-            (tap) => tap.name === PLUGIN_NAME
-          )
-        ) {
+        if (!watchRunInitialized) {
+          watchRunInitialized = true;
           compiler.hooks.beforeCompile.tapAsync(
             PLUGIN_NAME,
             async (params, callback) => {
@@ -127,11 +135,9 @@ export class AngularRspackPlugin implements RspackPluginInstance {
                 this.#sourceFileCache.typeScriptFileCache,
                 this.#javascriptTransformer
               );
-              compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
-                watchingModifiedFiles.forEach((file) => {
-                  compilation.fileDependencies.add(file);
-                });
-              });
+
+              // Update shared state for compilation hook
+              currentWatchingModifiedFiles = watchingModifiedFiles;
 
               callback();
             }
@@ -264,43 +270,49 @@ export class AngularRspackPlugin implements RspackPluginInstance {
       callback();
     });
 
+    // Store compilation reference for budget checking in done hook
+    let currentEmitCompilation: Compilation | undefined;
+
     compiler.hooks.afterEmit.tap(PLUGIN_NAME, (compilation) => {
-      // Check for budget errors and display them to the user.
+      currentEmitCompilation = compilation;
+    });
+
+    // Register done hook once - checks budgets using stored compilation
+    compiler.hooks.done.tap(PLUGIN_NAME + '_budgets', (statsValue) => {
+      if (!currentEmitCompilation) return;
+
       const budgets = this.#_options.budgets;
-      let budgetFailures: BudgetCalculatorResult[] | undefined;
-
-      compiler.hooks.done.tap(PLUGIN_NAME, (statsValue) => {
-        const stats = statsValue.toJson();
-        const isPlatformServer = Array.isArray(compiler.options.target)
-          ? compiler.options.target.some(
-              (target) => target === 'node' || target == 'async-node'
-            )
-          : compiler.options.target === 'node' ||
-            compiler.options.target === 'async-node';
-        if (budgets?.length && !isPlatformServer) {
-          budgetFailures = [...checkBudgets(budgets, stats)];
-          for (const { severity, message } of budgetFailures) {
-            switch (severity) {
-              case ThresholdSeverity.Warning:
-                addWarning(compilation, {
-                  message,
-                  name: PLUGIN_NAME,
-                  hideStack: true,
-                });
-                break;
-              case ThresholdSeverity.Error:
-                addError(compilation, {
-                  message,
-                  name: PLUGIN_NAME,
-                  hideStack: true,
-                });
-                break;
-              default:
-                assertNever(severity);
-            }
+      const stats = statsValue.toJson();
+      const isPlatformServer = Array.isArray(compiler.options.target)
+        ? compiler.options.target.some(
+            (target) => target === 'node' || target == 'async-node'
+          )
+        : compiler.options.target === 'node' ||
+          compiler.options.target === 'async-node';
+
+      if (budgets?.length && !isPlatformServer) {
+        const budgetFailures = [...checkBudgets(budgets, stats)];
+        for (const { severity, message } of budgetFailures) {
+          switch (severity) {
+            case ThresholdSeverity.Warning:
+              addWarning(currentEmitCompilation, {
+                message,
+                name: PLUGIN_NAME,
+                hideStack: true,
+              });
+              break;
+            case ThresholdSeverity.Error:
+              addError(currentEmitCompilation, {
+                message,
+                name: PLUGIN_NAME,
+                hideStack: true,
+              });
+              break;
+            default:
+              assertNever(severity);
           }
         }
-      });
+      }
     });
 
     compiler.hooks.afterDone.tap(PLUGIN_NAME, (stats) => {

packages/angular-rspack/src/lib/plugins/watch-file-logs-plugin.ts

@@ -12,19 +12,29 @@ const PLUGIN_NAME = 'AngularRspackWatchFilesLogsPlugin';
 
 export class WatchFilesLogsPlugin implements RspackPluginInstance {
   apply(compiler: Compiler) {
+    let currentModifiedFiles: ReadonlySet<string> | undefined;
+    let currentRemovedFiles: ReadonlySet<string> | undefined;
+
+    // Register compilation hook once - logs modified/removed files
+    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
+      const logger = compilation.getLogger(PLUGIN_NAME);
+      if (currentModifiedFiles?.size) {
+        logger.log(
+          `Modified files:\n${[...currentModifiedFiles].join('\n')}\n`
+        );
+      }
+
+      if (currentRemovedFiles?.size) {
+        logger.log(`Removed files:\n${[...currentRemovedFiles].join('\n')}\n`);
+      }
+    });
+
+    // Update shared state on each watch cycle
     compiler.hooks.watchRun.tap(
       PLUGIN_NAME,
       ({ modifiedFiles, removedFiles }) => {
-        compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
-          const logger = compilation.getLogger(PLUGIN_NAME);
-          if (modifiedFiles?.size) {
-            logger.log(`Modified files:\n${[...modifiedFiles].join('\n')}\n`);
-          }
-
-          if (removedFiles?.size) {
-            logger.log(`Removed files:\n${[...removedFiles].join('\n')}\n`);
-          }
-        });
+        currentModifiedFiles = modifiedFiles;
+        currentRemovedFiles = removedFiles;
       }
     );
   }