chokidar

High-level changes

• Rewrote the watcher around a single observation pipeline. Backend callbacks are treated as invalidations and confirmed with lstat, stat, or readdir before any event is emitted, so the final state after a burst of changes matches the filesystem.

• Added native recursive watching through fs.watch({ recursive: true }). The default auto backend uses it on macOS and Windows and per-directory watching elsewhere.

• Shared native handles across watchers and opened them per directory only: files no longer own handles. This fixes EBADF errors when watching many files on macOS (#1385, #1452).

• Replaced fs.watchFile with Chokidar-owned stat polling. Poll loops are shared across watchers at the fastest requested interval.

• Required Node.js 22.22 or later.

API changes

• Added the backend option: 'auto' (default), 'native', 'native-recursive', or 'polling'.

  • usePolling: true remains as a deprecated alias for backend: 'polling'.

• Renamed interval and binaryInterval to pollingInterval and pollingBinaryInterval.

  • The old names remain as deprecated aliases; the new names win when both are given.

• Changed the atomic default to false with polling. An explicit value is preserved.

• Made close() terminal: add() now throws once closing has started. Construct a new watcher instead.

• Validated options in the constructor: invalid backend, atomic, depth, awaitWriteFinish, and polling intervals throw TypeError.

• Emitted errors from add() as error events instead of unhandled rejections (#1378).

• Made getWatched() return a null-prototype object, so a watched directory named __proto__ is listed (#1493). Use Object.hasOwn() instead of hasOwnProperty() on the result.

• Stopped applying ignored to directories above a path passed to watch() or add(), so a missing path is still watched through its parent (#1374). Other entries in those directories are still filtered.

Fixes

• Fixed a 100% CPU loop when the process working directory containing a relatively watched file was deleted (#1474).

• Fixed watching a filesystem root, which emitted unlink and unlinkDir for every entry (#1184, #452).

• Fixed UNKNOWN errors from fs.watch on macOS sockets, which prevented watching /var/run (#1391).

• Fixed a symlink whose target passes through a regular file (ENOTDIR) disabling watching of its directory and preventing ready (#1476).

• Fixed files created in a newly added directory between its scan and watch registration being missed (#1471).

• Fixed watching a missing nested path stopping its parent directory's subtree from being watched (#1470).

• Fixed false change events on Windows when many sibling files are written (#1466).

• Fixed duplicate add events for unchanged files under directory activity (#1465).

• Fixed replacing a watched directory with a file of the same name hanging the process (#1464).

• Fixed persistent watching stopping after a watched directory was removed (#1463).

• Fixed a deleted watched path not being reported when recreated: previously only a deleted file that was the sole watched path was watched for its return. Any path passed to watch() or add() is now awaited from its nearest existing parent.

• Fixed event throttling discarding updates; the newest differing change is now replayed when the window closes (#1455).

• Fixed relative ignored paths; relative strings now resolve against cwd or the process working directory (#1436).

• Fixed files not being detected when their directory did not exist before watching (#1422).

• Fixed removed files being reported as unlinkDir instead of unlink (#1421).

• Fixed ignored files and directories still being watched in WSL (#1418).

• Fixed change being reported for every file when one file changed under Deno (#1417).

• Fixed changes not being detected after the second save (#1399).

• Fixed renaming a watched directory that contains subdirectories on Windows (#1380, #1398).

• Fixed re-watching a path not honoring ignoreInitial (#1386).

• Fixed EISDIR errors during the initial scan of network drives (#1376).

• Fixed watching an array of absolute file paths (#1366).

• Fixed unwatching a deleted watched directory on Windows, contributed

• Documented that unwatched paths stay ignored until they are added again (#1439).

Misc

• Made the Stats import type-only, contributed

• Pinned dev dependencies and restricted workflow permissions, contributed