chokidar
6.0.0 · 19 Oct 2026MIT292.3M / weekRepositorynpmAtom feed
Summary· from the note as AI read it
Migration neededRead before upgrading: 7 changes to make.
Before you upgrade
- Set atomic explicitly if relying on it with polling
- Don't call add() after close(); create a new watcher
- Check options are valid; invalid values now throw TypeError
- Handle add() failures via error event listeners, not rejections
- Use Object.hasOwn() instead of hasOwnProperty() on getWatched() result
- ignored no longer applies to ancestors of watched paths; check filters
New minimums
- Upgrade to Node.js 22.22 or later
Deprecated
- Replace usePolling: true with backend: 'polling'
- Rename interval/binaryInterval to pollingInterval/pollingBinaryInterval
- Old interval option names are deprecated aliases; switch to new names
New
- Added native recursive watching through
fs.watch({ recursive: true }). The defaultautobackend uses it on macOS and Windows and per-directory watching elsewhere. - Replaced
fs.watchFilewith Chokidar-owned stat polling. Poll loops are shared across watchers at the fastest requested interval. - Added the
backendoption:'auto'(default),'native','native-recursive', or'polling'.
In short
7 breaking3 deprecated2 new1 faster25 fixed3 internal
- Breaking
Required Node.js 22.22 or later.
- Breaking
Changed the
atomicdefault tofalsewith polling. An explicit value is preserved. - Breaking
Made
close()terminal:add()now throws once closing has started. Construct a new watcher instead. - Breaking
Validated options in the constructor: invalid
backend,atomic,depth,awaitWriteFinish, and polling intervals throwTypeError. - Breaking
Emitted errors from
add()aserrorevents instead of unhandled rejections. - Breaking
Made
getWatched()return a null-prototype object, so a watched directory named__proto__is listed (#1493). UseObject.hasOwn()instead ofhasOwnProperty()on the result. - Breaking
Stopped applying
ignoredto directories above a path passed towatch()oradd(), so a missing path is still watched through its parent (#1374). Other entries in those directories are still filtered. - Deprecated
usePolling: trueremains as a deprecated alias forbackend: 'polling'.
Release note
High-level changes
Rewrote the watcher around a single observation pipeline. Backend callbacks are treated as invalidations and confirmed with
lstat,stat, orreaddirbefore 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 defaultautobackend 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
EBADFerrors when watching many files on macOS (#1385, #1452).Replaced
fs.watchFilewith Chokidar-owned stat polling. Poll loops are shared across watchers at the fastest requested interval.- Breaking
Required Node.js 22.22 or later.
API changes
Added the
backendoption:'auto'(default),'native','native-recursive', or'polling'.usePolling: trueremains as a deprecated alias forbackend: 'polling'.
Renamed
intervalandbinaryIntervaltopollingIntervalandpollingBinaryInterval.The old names remain as deprecated aliases; the new names win when both are given.
Changed the
atomicdefault tofalsewith 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 throwTypeError.Emitted errors from
add()aserrorevents instead of unhandled rejections (#1378).Made
getWatched()return a null-prototype object, so a watched directory named__proto__is listed (#1493). UseObject.hasOwn()instead ofhasOwnProperty()on the result.Stopped applying
ignoredto directories above a path passed towatch()oradd(), 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
unlinkandunlinkDirfor every entry (#1184, #452).Fixed
UNKNOWNerrors fromfs.watchon 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 preventingready(#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
changeevents on Windows when many sibling files are written (#1466).Fixed duplicate
addevents 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()oradd()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
ignoredpaths; relative strings now resolve againstcwdor 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
unlinkDirinstead ofunlink(#1421).Fixed ignored files and directories still being watched in WSL (#1418).
Fixed
changebeing 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
EISDIRerrors 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).
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.