NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm, #83 most downloaded on npm
Minimal and efficient cross-platform file watching library
Latest stable
6.0.0
Last release 1 months ago
19 Oct 2026
Release timing varies
gaps range from 9 days to 2.1 years
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
15 years old
110 releases · first in 2012
Drag across the ruler to compare, or tap a release to open it.
usePolling: true remains as a deprecated alias for backend: 'polling' .
lstat, stat, or readdir before any event is emitted, so the final state after a burst of changes matches the filesystem.fs.watch({ recursive: true }). The default auto backend uses it on macOS and Windows and per-directory watching elsewhere.EBADF errors when watching many files on macOS (#1385, #1452).fs.watchFile with Chokidar-owned stat polling. Poll loops are shared across watchers at the fastest requested interval.backend option: 'auto' (default), 'native', 'native-recursive', or 'polling'.
usePolling: true remains as a deprecated alias for backend: 'polling'.interval and binaryInterval to pollingInterval and pollingBinaryInterval.
atomic default to false with polling. An explicit value is preserved.close() terminal: add() now throws once closing has started. Construct a new watcher instead.backend, atomic, depth, awaitWriteFinish, and polling intervals throw TypeError.add() as error events instead of unhandled rejections (#1378).getWatched() return a null-prototype object, so a watched directory named __proto__ is listed (#1493). Use Object.hasOwn() instead of hasOwnProperty() on the result.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.unlink and unlinkDir for every entry (#1184, #452).UNKNOWN errors from fs.watch on macOS sockets, which prevented watching /var/run (#1391).ENOTDIR) disabling watching of its directory and preventing ready (#1476).change events on Windows when many sibling files are written (#1466).add events for unchanged files under directory activity (#1465).watch() or add() is now awaited from its nearest existing parent.ignored paths; relative strings now resolve against cwd or the process working directory (#1436).unlinkDir instead of unlink (#1421).change being reported for every file when one file changed under Deno (#1417).ignoreInitial (#1386).EISDIR errors during the initial scan of network drives (#1376).Stats import type-only, contributed by @zhennann in pull request #1447.Full Changelog: 5.0.0...6.0.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Make the package ESM-only. Reduces on-disk package size from ~150kb to ~80kb
Full Changelog: 4.0.3...5.0.0
isolatedDeclarations-based TypeScript for simpler auto-generated docs.Fix typescript type of emitted args by @43081j in #1397
Full Changelog: 4.0.2...4.0.3
error arguments, contributed by @43081j in pull request #1397.Fix test "should detect safe-edit" on FreeBSD by @tagattie in #1375
Full Changelog: 4.0.1...4.0.2
.map files, contributed by @bluwy in pull request #1383.Various fixes and improvements of typescript types
Full Changelog: 4.0.0...4.0.1
watch() to be undefined, contributed by @benmccann in pull request #1349.Decrease dependency count from 13 to 1
Special thanks to @43081j for improvements and help.
Full Changelog: 3.6.0...4.0.0
ignored, or expand globs yourself; see the README's upgrading section.fix readyCount logic by @JLHwung in #1288
Full Changelog: 3.5.3...3.6.0
ready count logic, contributed by @JLHwung in pull request #1288.MustScanSubDirs flag, contributed by @MarcCelani-at in pull request #1197.fs.FSWatcher types for Node.js 16 and later, contributed by @ben-polinsky in pull request #1300.types: use correct type def for ignored option by @iheyunfei in #1140
add and unwatch TypeScript definitions by @alan-agius4 in #1157Full Changelog: 3.5.2...3.5.3
ignored option, contributed by @hyfdev in pull request #1140.add and unwatch TypeScript definitions, contributed by @alan-agius4 in pull request #1157.yarn.lock, contributed by @alan-agius4 in pull requests #1158 and #1159."Update" glob-parent dependency from ~5.1.0 to ~5.1.2 to silence "vulnerability" warnings
"Update" glob-parent dependency from ~5.1.0 to ~5.1.2 to silence "vulnerability" warnings
~5.1.0 to ~5.1.2 to silence vulnerability warnings.Symlink fixes
Support for ARM Macs with Apple Silicon.
Stopped watching circular symlinks that point to a parent directory, preventing infinite loops.
Fixes an ability to watch network drives on windows.
Fixes an ability to watch network drives on windows.
Fixed files not being watched properly by a new watcher after a previous one was closed.
Support for directory-based symlinks.
.on() event handlers.followSymlinks: false on macOS still follows symlinked directories.- Updated fsevents and readdirp.
FSWatcher#close() method became async. This ensures IO operations are finished properly and fixes a few segfaulty crashes.
FSWatcher#close() method became async. This ensures IO operations are finished properly and fixes a few segfaulty crashes.
close() async. This ensures I/O operations finish properly and fixes a few segfaults.Fixed memory leaks for directories that change frequently over a long time, present since 3.0.
Fixed a resource-starved CPU preventing ready by updating fsevents (#873).
ready by updating fsevents (#873).Improve Linux RAM usage by 50%. Stability optimizations. Race condition fixes. Windows glob fixes.
Improve Linux RAM usage by 50%. Stability optimizations. Race condition fixes. Windows glob fixes.
package.json from 8.16 to 8.0.Improved Linux RAM usage by 50%.
~ instead of ^ for stability.Fixes "Expected pattern to be a non-empty string"
Fixes "Expected pattern to be a non-empty string" (#871)
Dotfiles are no longer filtered out by default. Use ignored option if needed.
Dotfiles are no longer filtered out by default. Use ignored option if needed.
Improve Linux performance by 50%.
ignored option if needed.realpath calls (#882)..add() returning a promise and other type issues.Brings bigint support to stat outputs on windows.
bigint support to stat outputs on windows.ready event emission for symlink directories.bigint support to stat outputs on Windows.ready emission for symlinked directories.Fixes "Assertion failed" errors when a watcher is closed
Massive CPU & RAM consumption improvements. 17x package & deps size reduction. Node 8+-only
Massive CPU & RAM consumption improvements. 17x package & deps size reduction. Node 8+-only
Republished 2.1.7 to fix its npm dist-tag.
Fixed close() preventing the process from exiting when watching globs.
close() preventing the process from exiting when watching globs.Reverted the atomic-writes workaround from 2.1.3.
Improved TypeScript type definitions for the on method.
on method.Improved handling of atomic writes.
Added TypeScript type definitions.
Handled simultaneous changes of access time and modification time (#793).
Ignored access-time updates caused by read operations (#762).
lodash.debounce.- Fixed close() crashing (#730).
close() crashing (#730).Fixed file descriptor 0 not being closed on Windows after an EPERM error.
EPERM error.Allowed semver range updates for the upath dependency.
Fixed globs on Windows when using ignored and cwd (#668), thanks to @remy.
Breaking: upgraded globbing dependencies, which require stricter globs with POSIX-style slashes, because Windows-style slashes are escape sequences.
CHOKIDAR_PRINT_FSEVENTS_REQUIRE_ERROR environment variable to log FSEvents require errors.Added the disableGlobbing option.
disableGlobbing option.CHOKIDAR_INTERVAL environment variable to force the polling interval.close() being called before ready.- Fixed a symlink issue.
Added the CHOKIDAR_USEPOLLING environment variable to force polling mode.
CHOKIDAR_USEPOLLING environment variable to force polling mode.Fixed missing addDir events when using the cwd and alwaysStat options.
addDir events when using the cwd and alwaysStat options.add events for files within a renamed directory.Consolidated watch instances on many siblings to their common parent, to avoid exhausting FSEvents system limits.
Made the debounce delay used with atomic: true customizable.
atomic: true customizable.awaitWriteFinish.Updated the async-each dependency to ^1.0.0.
^1.0.0.Fixed emitting stats with the awaitWriteFinish option.
stats with the awaitWriteFinish option.Allowed subclassing the watcher with ES6 class syntax.
Added the getWatched() method, exposing all file system entries being watched.
Improved awaitWriteFinish behavior and made it compatible with cwd.
awaitWriteFinish behavior and made it compatible with cwd.cwd behavior on Windows.add instead of change when a previously deleted file is added again.Allowed nested arrays of paths in watch() and add().
watch() and add().awaitWriteFinish option.Updated dependencies, including fsevents 1.0.0, improving installation.
Fixed unwatch() with relative paths.
unwatch() with relative paths.Fixed a regression with regexes and functions in ignored.
ignored.Fixed ignored files and globs while the cwd option is set.
cwd option is set.Fixed a race with the alwaysStat option and removed files.
alwaysStat option and removed files.Fixed absolute paths and ENAMETOOLONG errors.
ENAMETOOLONG errors.Fixed close() in fs.watch mode with persistent: false.
close() in fs.watch mode with persistent: false.Added glob support in watch(), add(), and unwatch().
watch(), add(), and unwatch().unwatch() method.ignored accept a regex, function, glob, or array, through anymatch.cwd, depth, alwaysStat, followSymlinks, and atomic options.ready event, emitted when the initial scan is done.raw event, exposing data from the lower-level watch modules.Nothing published for this version
One column per quarter.