refactor(@angular-devkit/build-angular): convert watching to use watchpack package

The underlying file watching functionality now uses the `watchpack` library for all
builders. This includes the Webpack-based `browser` and the esbuild-based `application`/
`browser-esbuild`. This not only has the advantage of a single dependency for both but also
provides more consistent behavior between the two build system in regards to file watching.
Since the implementation of the file watching is fully encapsulated, there is no change to
the options or configurations of consuming applications.

Author: clydin

package.json

@@ -114,6 +114,7 @@
     "@types/shelljs": "^0.8.11",
     "@types/tar": "^6.1.2",
     "@types/text-table": "^0.2.1",
+    "@types/watchpack": "^2.4.4",
     "@types/yargs": "^17.0.20",
     "@types/yargs-parser": "^21.0.0",
     "@types/yarnpkg__lockfile": "^1.1.5",
@@ -211,6 +212,7 @@
     "verdaccio": "5.29.0",
     "verdaccio-auth-memory": "^10.0.0",
     "vite": "5.0.7",
+    "watchpack": "2.4.0",
     "webpack": "5.89.0",
     "webpack-dev-middleware": "6.1.1",
     "webpack-dev-server": "4.15.1",

packages/angular_devkit/build_angular/BUILD.bazel

@@ -154,14 +154,14 @@ ts_library(
         "@npm//@types/picomatch",
         "@npm//@types/semver",
         "@npm//@types/text-table",
+        "@npm//@types/watchpack",
         "@npm//@vitejs/plugin-basic-ssl",
         "@npm//ajv",
         "@npm//ansi-colors",
         "@npm//autoprefixer",
         "@npm//babel-loader",
         "@npm//babel-plugin-istanbul",
         "@npm//browserslist",
-        "@npm//chokidar",
         "@npm//copy-webpack-plugin",
         "@npm//critters",
         "@npm//css-loader",
@@ -202,6 +202,7 @@ ts_library(
         "@npm//typescript",
         "@npm//undici",
         "@npm//vite",
+        "@npm//watchpack",
         "@npm//webpack",
         "@npm//webpack-dev-middleware",
         "@npm//webpack-dev-server",

packages/angular_devkit/build_angular/package.json

@@ -27,7 +27,6 @@
     "babel-loader": "9.1.3",
     "babel-plugin-istanbul": "6.1.1",
     "browserslist": "^4.21.5",
-    "chokidar": "3.5.3",
     "copy-webpack-plugin": "11.0.0",
     "critters": "0.0.20",
     "css-loader": "6.8.1",
@@ -65,6 +64,7 @@
     "tslib": "2.6.2",
     "undici": "6.0.1",
     "vite": "5.0.7",
+    "watchpack": "2.4.0",
     "webpack": "5.89.0",
     "webpack-dev-middleware": "6.1.1",
     "webpack-dev-server": "4.15.1",

packages/angular_devkit/build_angular/src/builders/application/build-action.ts

@@ -8,6 +8,7 @@
 
 import { BuilderOutput } from '@angular-devkit/architect';
 import type { logging } from '@angular-devkit/core';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { BuildOutputFile } from '../../tools/esbuild/bundler-context';
 import { ExecutionResult, RebuildState } from '../../tools/esbuild/bundler-execution-result';
@@ -115,7 +116,11 @@ export async function* runEsBuildBuildAction(
       '.pnp.data.json',
     ];
 
-    watcher.add(packageWatchFiles.map((file) => path.join(workspaceRoot, file)));
+    watcher.add(
+      packageWatchFiles
+        .map((file) => path.join(workspaceRoot, file))
+        .filter((file) => existsSync(file)),
+    );
 
     // Watch locations provided by the initial build result
     watcher.add(result.watchFiles);

packages/angular_devkit/build_angular/src/tools/esbuild/watcher.ts

@@ -6,8 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import { FSWatcher } from 'chokidar';
-import { extname, normalize } from 'node:path';
+import WatchPack from 'watchpack';
 
 export class ChangedFiles {
   readonly added = new Set<string>();
@@ -41,93 +40,44 @@ export function createWatcher(options?: {
   ignored?: string[];
   followSymlinks?: boolean;
 }): BuildWatcher {
-  const watcher = new FSWatcher({
-    usePolling: options?.polling,
-    interval: options?.interval,
+  const watcher = new WatchPack({
+    poll: options?.polling ? options?.interval ?? true : false,
     ignored: options?.ignored,
     followSymlinks: options?.followSymlinks,
-    disableGlobbing: true,
-    ignoreInitial: true,
+    aggregateTimeout: 250,
   });
+  const watchedFiles = new Set<string>();
 
   const nextQueue: ((value?: ChangedFiles) => void)[] = [];
-  let currentChanges: ChangedFiles | undefined;
-  let nextWaitTimeout: NodeJS.Timeout | undefined;
-
-  /**
-   * We group the current events in a map as on Windows with certain IDE a file contents change can trigger multiple events.
-   *
-   * Example:
-   * rename | 'C:/../src/app/app.component.css'
-   * rename | 'C:/../src/app/app.component.css'
-   * change | 'C:/../src/app/app.component.css'
-   *
-   */
-  let currentEvents: Map</* Event name */ string, /* File path */ string> | undefined;
-
-  /**
-   * Using `watcher.on('all')` does not capture some of events fired when using Visual studio and this does not happen all the time,
-   * but only after a file has been changed 3 or more times.
-   *
-   * Also, some IDEs such as Visual Studio (not VS Code) will fire a rename event instead of unlink when a file is renamed or changed.
-   *
-   * Example:
-   * ```
-   * watcher.on('raw')
-   * Change 1
-   * rename | 'C:/../src/app/app.component.css'
-   * rename | 'C:/../src/app/app.component.css'
-   * change | 'C:/../src/app/app.component.css'
-   *
-   * Change 2
-   * rename | 'C:/../src/app/app.component.css'
-   * rename | 'C:/../src/app/app.component.css'
-   * change | 'C:/../src/app/app.component.css'
-   *
-   * Change 3
-   * rename | 'C:/../src/app/app.component.css'
-   * rename | 'C:/../src/app/app.component.css'
-   * change | 'C:/../src/app/app.component.css'
-   *
-   * watcher.on('all')
-   * Change 1
-   * change | 'C:\\..\\src\\app\\app.component.css'
-   *
-   * Change 2
-   * unlink | 'C:\\..\\src\\app\\app.component.css'
-   *
-   * Change 3
-   * ... (Nothing)
-   * ```
-   */
-  watcher
-    .on('raw', (event, path, { watchedPath }) => {
-      if (watchedPath && !extname(watchedPath)) {
-        // Ignore directories, file changes in directories will be fired seperatly.
-        return;
-      }
+  let currentChangedFiles: ChangedFiles | undefined;
 
-      switch (event) {
-        case 'rename':
-        case 'change':
-          // When polling is enabled `watchedPath` can be undefined.
-          // `path` is always normalized unlike `watchedPath`.
-          const changedPath = watchedPath ? normalize(watchedPath) : path;
-          handleFileChange(event, changedPath);
-          break;
-      }
-    })
-    .on('all', handleFileChange);
+  watcher.on('aggregated', (changes, removals) => {
+    const changedFiles = currentChangedFiles ?? new ChangedFiles();
+    for (const file of changes) {
+      changedFiles.modified.add(file);
+    }
+    for (const file of removals) {
+      changedFiles.removed.add(file);
+    }
+
+    const next = nextQueue.shift();
+    if (next) {
+      currentChangedFiles = undefined;
+      next(changedFiles);
+    } else {
+      currentChangedFiles = changedFiles;
+    }
+  });
 
   return {
     [Symbol.asyncIterator]() {
       return this;
     },
 
     async next() {
-      if (currentChanges && nextQueue.length === 0) {
-        const result = { value: currentChanges };
-        currentChanges = undefined;
+      if (currentChangedFiles && nextQueue.length === 0) {
+        const result = { value: currentChangedFiles };
+        currentChangedFiles = undefined;
 
         return result;
       }
@@ -138,19 +88,42 @@ export function createWatcher(options?: {
     },
 
     add(paths) {
-      watcher.add(paths);
+      const previousSize = watchedFiles.size;
+      if (typeof paths === 'string') {
+        watchedFiles.add(paths);
+      } else {
+        for (const file of paths) {
+          watchedFiles.add(file);
+        }
+      }
+
+      if (previousSize !== watchedFiles.size) {
+        watcher.watch({
+          files: watchedFiles,
+        });
+      }
     },
 
     remove(paths) {
-      watcher.unwatch(paths);
+      const previousSize = watchedFiles.size;
+      if (typeof paths === 'string') {
+        watchedFiles.delete(paths);
+      } else {
+        for (const file of paths) {
+          watchedFiles.delete(file);
+        }
+      }
+
+      if (previousSize !== watchedFiles.size) {
+        watcher.watch({
+          files: watchedFiles,
+        });
+      }
     },
 
     async close() {
       try {
-        await watcher.close();
-        if (nextWaitTimeout) {
-          clearTimeout(nextWaitTimeout);
-        }
+        watcher.close();
       } finally {
         let next;
         while ((next = nextQueue.shift()) !== undefined) {
@@ -159,51 +132,4 @@ export function createWatcher(options?: {
       }
     },
   };
-
-  function handleFileChange(event: string, path: string): void {
-    switch (event) {
-      case 'add':
-      case 'change':
-      // When using Visual Studio the rename event is fired before a change event when the contents of the file changed
-      // or instead of `unlink` when the file has been renamed.
-      case 'unlink':
-      case 'rename':
-        currentEvents ??= new Map();
-        currentEvents.set(path, event);
-        break;
-      default:
-        return;
-    }
-
-    // Wait 250ms from next change to better capture groups of file save operations.
-    if (!nextWaitTimeout) {
-      nextWaitTimeout = setTimeout(() => {
-        nextWaitTimeout = undefined;
-        const next = nextQueue.shift();
-        if (next && currentEvents) {
-          const events = currentEvents;
-          currentEvents = undefined;
-
-          const currentChanges = new ChangedFiles();
-          for (const [path, event] of events) {
-            switch (event) {
-              case 'add':
-                currentChanges.added.add(path);
-                break;
-              case 'change':
-                currentChanges.modified.add(path);
-                break;
-              case 'unlink':
-              case 'rename':
-                currentChanges.removed.add(path);
-                break;
-            }
-          }
-
-          next(currentChanges);
-        }
-      }, 250);
-      nextWaitTimeout?.unref();
-    }
-  }
 }

yarn.lock

@@ -3707,6 +3707,13 @@
     "@types/minimatch" "*"
     "@types/node" "*"
 
+"@types/graceful-fs@*":
+  version "4.1.9"
+  resolved "https://registry.yarnpkg.com/@types/graceful-fs/-/graceful-fs-4.1.9.tgz#2a06bc0f68a20ab37b3e36aa238be6abdf49e8b4"
+  integrity sha512-olP3sd1qOEe5dXTSaFvQG+02VdRXcdytWLAZsAq1PecU8uqQAhkrnbli7DagjtXKW/Bl7YJbUsa8MPcuc8LHEQ==
+  dependencies:
+    "@types/node" "*"
+
 "@types/http-errors@*":
   version "2.0.4"
   resolved "https://registry.yarnpkg.com/@types/http-errors/-/http-errors-2.0.4.tgz#7eb47726c391b7345a6ec35ad7f4de469cf5ba4f"
@@ -4051,6 +4058,14 @@
   resolved "https://registry.yarnpkg.com/@types/uuid/-/uuid-9.0.7.tgz#b14cebc75455eeeb160d5fe23c2fcc0c64f724d8"
   integrity sha512-WUtIVRUZ9i5dYXefDEAI7sh9/O7jGvHg7Df/5O/gtH3Yabe5odI3UWopVR1qbPXQtvOxWu3mM4XxlYeZtMWF4g==
 
+"@types/watchpack@^2.4.4":
+  version "2.4.4"
+  resolved "https://registry.yarnpkg.com/@types/watchpack/-/watchpack-2.4.4.tgz#d492bca62ba73cf041eda26e494fe7a540852836"
+  integrity sha512-SbuSavsPxfOPZwVHBgQUVuzYBe6+8KL7dwiJLXaj5rmv3DxktOMwX5WP1J6UontwUbewjVoc7pCgZvqy6rPn+A==
+  dependencies:
+    "@types/graceful-fs" "*"
+    "@types/node" "*"
+
 "@types/webpack-sources@*":
   version "3.2.3"
   resolved "https://registry.yarnpkg.com/@types/webpack-sources/-/webpack-sources-3.2.3.tgz#b667bd13e9fa15a9c26603dce502c7985418c3d8"
@@ -12820,7 +12835,7 @@ walk-up-path@^1.0.0:
   resolved "https://registry.yarnpkg.com/walk-up-path/-/walk-up-path-1.0.0.tgz#d4745e893dd5fd0dbb58dd0a4c6a33d9c9fec53e"
   integrity sha512-hwj/qMDUEjCU5h0xr90KGCf0tg0/LgJbmOWgrWKYlcJZM7XvquvUJZ0G/HMGr7F7OQMOUuPHWP9JpriinkAlkg==
 
-watchpack@^2.4.0:
+watchpack@2.4.0, watchpack@^2.4.0:
   version "2.4.0"
   resolved "https://registry.yarnpkg.com/watchpack/-/watchpack-2.4.0.tgz#fa33032374962c78113f93c7f2fb4c54c9862a5d"
   integrity sha512-Lcvm7MGST/4fup+ifyKi2hjyIAwcdI4HRgtvTpIUxBRhB+RFtUh8XtDOxUfctVCnhVi+QQj49i91OyvzkJl6cg==