Packages

chokidar

6.0.0 · 19 Oct 2026MIT292.3M / weekRepositorynpmAtom feed

Your version

6.0.0

Latestmajor19 Oct 2026Where it was published

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 default auto backend uses it on macOS and Windows and per-directory watching elsewhere.
  • Replaced fs.watchFile with Chokidar-owned stat polling. Poll loops are shared across watchers at the fastest requested interval.
  • Added the backend option: '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 atomic default to false with 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 throw TypeError.

  • Breaking

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

  • Breaking

    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.

  • Breaking

    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.

  • Deprecated

    usePolling: true remains as a deprecated alias for backend: '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, 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.

  • Breaking

    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).

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.