File System Watching Strategies for Node.js Tooling
These libraries monitor file system changes to trigger builds, reload servers, or sync data. chokidar is the cross-platform standard, while watchpack targets bundlers. Older tools like watch and gaze offer legacy patterns but lack modern maintenance. node-watch provides a pure JavaScript alternative without native dependencies. sane and filewatcher serve niche historical roles but carry stability risks in current environments.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
File System Watching Strategies for Node.js Tooling
Monitoring file changes is a core requirement for development servers, build pipelines, and test runners. The packages chokidar, filewatcher, gaze, node-watch, sane, watch, and watchpack all solve this problem but differ significantly in stability, API design, and maintenance status. Let's break down how they handle common engineering challenges.
π οΈ Initialization & API Style
The way you start watching files varies from event emitters to callback-based systems. Understanding the setup helps you integrate them into your tooling.
chokidar uses an event emitter pattern that is familiar to most Node.js developers.
const chokidar = require('chokidar');
const watcher = chokidar.watch('src/**/*.js', {
ignored: /node_modules/
});
filewatcher requires creating an instance and adding files manually.
const fw = require('filewatcher')();
fw.add('src/main.js');
fw.add('src/utils.js');
gaze uses a callback function that returns the watcher instance.
const gaze = require('gaze');
gaze('src/**/*.js', function (err, watcher) {
// watcher is ready
});
node-watch offers a simple function call that returns an emitter.
const watch = require('node-watch');
const watcher = watch('src', { recursive: true });
sane provides a standard watcher interface similar to chokidar.
const sane = require('sane');
const watcher = sane.watch('src');
watch uses a static method to create the watcher.
const watch = require('watch');
watch.watchCreate('src', function (err, files) {
// setup complete
});
watchpack requires instantiating a class and passing configuration objects.
const Watchpack = require('watchpack');
const watcher = new Watchpack({
aggregateTimeout: 1000
});
π Event Handling & Change Detection
How you listen for changes determines how your build logic responds to file updates.
chokidar emits specific events like change, add, and unlink.
watcher.on('change', path => {
console.log(`File ${path} changed`);
});
filewatcher triggers a single change event with the filename.
fw.on('change', function (filename) {
console.log(`File ${filename} changed`);
});
gaze emits changed events within the callback context.
watcher.on('changed', function (file) {
console.log(`File ${file} changed`);
});
node-watch passes the event type and filename to the callback.
watcher.on('update', function (evt, name) {
console.log(`File ${name} changed`);
});
sane emits change events with the file path and root.
watcher.on('change', function (filePath, root) {
console.log(`File ${filePath} changed`);
});
watch passes the event type and filename to the callback.
watch.watchMonitor('src', function (event, filename) {
console.log(`File ${filename} ${event}`);
});
watchpack aggregates events and fires a single aggregated callback.
watcher.watch({ files: ['src/index.js'], directories: [] });
watcher.on('aggregated', function (changes, removals) {
console.log(`Changes: ${changes}`);
});
π Globbing & Pattern Matching
Selecting which files to watch is critical for performance and correctness.
chokidar supports glob patterns directly in the watch path.
chokidar.watch('src/**/*.js', { ignored: /node_modules/ });
filewatcher does not support globs natively; you must resolve paths yourself.
// Must manually resolve files before adding
const files = resolveFiles('src');
files.forEach(f => fw.add(f));
gaze was built specifically for globbing support.
gaze('**/*.js', { cwd: 'src' }, function (err, watcher) {
// Watches all JS files
});
node-watch supports filtering via options but not full globs in path.
watch('src', {
filter: name => /\.js$/.test(name)
});
sane supports ignoring patterns via configuration.
sane.watch('src', { glob: ['**/*.js'] });
watch requires manual filtering or external glob libraries.
// No built-in glob support in base API
watch.watchTree('src', function (f, curr, prev) {
if (/\.js$/.test(f)) { /* handle */ }
});
watchpack handles patterns through the files/directories configuration.
watcher.watch({
files: ['src/index.js'],
directories: ['src/components']
});
β οΈ Maintenance & Stability Status
Choosing a library with active maintenance prevents future breakage during Node upgrades.
chokidar is actively maintained and the industry standard.
- β Safe for production use.
- β Handles native OS quirks automatically.
filewatcher relies on native C++ bindings.
- β Risk of breakage on Node version upgrades.
- β Harder to install in restricted environments.
gaze is stable but less active than chokidar.
- β οΈ Use only if globbing logic is tightly coupled.
- β οΈ Consider migrating to
chokidarfor long-term health.
node-watch is pure JavaScript and stable.
- β Good for simple use cases.
- β No compilation steps required.
sane is largely legacy within the Jest ecosystem.
- β Superseded by
jest-haste-map. - β Not recommended for general tooling.
watch is officially deprecated.
- β Do not use in new projects.
- β npm directs users to
chokidar.
watchpack is maintained by the Webpack team.
- β Safe for bundler development.
- β οΈ Overkill for simple task runners.
π Summary Table
| Package | Maintenance | Native Deps | Glob Support | Event Aggregation |
|---|---|---|---|---|
chokidar | β Active | β No | β Yes | β No |
filewatcher | β οΈ Low | β Yes | β No | β No |
gaze | β οΈ Low | β No | β Yes | β No |
node-watch | β Active | β No | β οΈ Filter Only | β No |
sane | β Legacy | β No | β Yes | β No |
watch | β Deprecated | β No | β No | β No |
watchpack | β Active | β No | β οΈ Config Based | β Yes |
π‘ Final Recommendation
For most frontend tooling tasks β such as hot reloading or build triggers β chokidar is the clear choice. It balances feature richness with stability and avoids the pitfalls of native bindings. Use watchpack only if you are building a bundler that needs to batch file events for performance. Avoid watch and sane in new projects due to deprecation and legacy status. If you need a pure JavaScript solution without extra dependencies, node-watch is a solid fallback. Always prioritize libraries with active maintenance to ensure compatibility with future Node.js versions.
How to Choose: chokidar vs filewatcher vs gaze vs node-watch vs sane vs watch vs watchpack
- chokidar:
Choose
chokidarfor most production tooling needs like dev servers or build watchers. It offers consistent behavior across Windows, macOS, and Linux without native bindings. The API is stable, well-documented, and handles edge cases like file renaming reliably. - filewatcher:
Avoid
filewatcherfor new projects unless you have a specific need for its native C++ bindings. The reliance on compiled modules often causes installation failures across different Node versions or CI environments. Modern pure JavaScript alternatives provide better stability. - gaze:
Choose
gazeonly if you are maintaining legacy codebases that depend on its specific globbing implementation. It supports file patterns out of the box, whichchokidaralso handles viagloboptions. New projects should preferchokidarfor better long-term support. - node-watch:
Choose
node-watchif you need a lightweight solution without any native dependencies or external requirements. It is written in pure JavaScript and works well for simple recursive watching tasks. However, it may lack some advanced features found inchokidar. - sane:
Avoid
sanefor new general-purpose tooling as it is largely superseded byjest-haste-mapwithin the Jest ecosystem. It was designed for specific performance needs in testing environments rather than general file watching. Modern alternatives offer better maintenance and community support. - watch:
Do not use
watchin new projects as it is officially deprecated and unmaintained. The npm page explicitly directs users to migrate tochokidarfor better cross-platform support. Continuing to use it introduces unnecessary risk and technical debt. - watchpack:
Choose
watchpackif you are building a module bundler similar to Webpack that requires event aggregation. It delays events to batch changes together, which reduces rebuild thrashing during massive file saves. It is specialized for high-performance bundling pipelines rather than general task running.
Popular Comparisons
README for chokidar
Chokidar 
Minimal and efficient cross-platform file watching library
Why?
Raw fs.watch / fs.watchFile are useless: fs.watch reports many changes as an
non-transparent rename, can fire twice for one change, and recursive watching differs across
platforms. Chokidar normalizes all of that:
- Proper
add/change/unlink(andaddDir/unlinkDir) events, verified, deduplicated, with paths on every platform. - Native
fs.watchby default, which keeps CPU usage down; stat-based polling is available for network and other unusual filesystems. - Recursive watching everywhere, with an optional depth limit, path filtering, and symlink support.
- Editor "atomic writes" (
atomic) and chunked writes of large files (awaitWriteFinish) are handled.
Chokidar watches everything under the paths you give it, so scope them (and use ignored /
depth) rather than watching more than you need.
Made for Brunch in 2012, it is now used in 30+ million projects and has proven itself in production environments. The current major is v6 (Oct 2026) - with lots of major improvements.
Getting started
npm install chokidar
import chokidar from 'chokidar';
// or: import { watch } from 'chokidar';
// or: const chokidar = require('chokidar');
chokidar.watch('src').on('all', (event, path) => console.log(event, path));
A fuller example:
import chokidar from 'chokidar';
const watcher = chokidar.watch('src', {
// strings are exact paths (not globs), regexes test the whole path, functions get (path, stats?)
ignored: [
/(^|\/)\../, // dotfiles
(path, stats) => stats?.isFile() && !path.endsWith('.js'), // only .js files
],
ignoreInitial: true, // don't emit add/addDir for files that already exist
});
watcher
.on('add', (path, stats) => console.log('added', path, stats?.size))
.on('change', (path) => console.log('changed', path))
.on('unlink', (path) => console.log('removed', path))
.on('ready', () => console.log('initial scan done'))
.on('error', (err) => console.error(err));
watcher.add(['lib', 'index.js']); // add more paths later
watcher.unwatch('lib'); // synchronous
console.log(watcher.getWatched()); // { '/abs': ['src'], '/abs/src': ['a.js', 'sub'], ... }
await watcher.close(); // async and terminal: create a new watcher to resume
Recipes:
// Large or chunked writes, and editors that save via temp file + rename
chokidar.watch('uploads', {
awaitWriteFinish: { stabilityThreshold: 2000, pollInterval: 100 }, // wait for size to settle
atomic: 100, // unlink + add within 100 ms becomes one change
});
// Network or otherwise unusual filesystems where fs.watch is unreliable
chokidar.watch('/mnt/nfs/data', { backend: 'polling', pollingInterval: 500 });
API
chokidar.watch(paths, [options]) returns an FSWatcher. paths is a string or an
array of strings; files are watched, directories are watched recursively. All options with their
defaults:
chokidar.watch('dir-or-file', {
// Filtering
ignored: undefined, // matcher or array of matchers, see below
ignoreInitial: false,
followSymlinks: true,
cwd: undefined,
depth: undefined, // unlimited
// Backend
backend: 'auto', // 'auto' | 'native' | 'native-recursive' | 'polling'
pollingInterval: 100, // polling backend only
pollingBinaryInterval: 300, // polling backend only
// Event timing
atomic: true, // false with backend: 'polling'; or a number of ms
awaitWriteFinish: false, // or true, or { stabilityThreshold: 2000, pollInterval: 100 }
alwaysStat: false,
// Errors and lifecycle
ignorePermissionErrors: false,
persistent: true,
});
Filtering
ignored(default: none). One matcher or an array of matchers. The whole path is tested (as passed towatch(), joined withcwdif set), not just the basename. Ignoring a directory ignores everything inside it. Directories above a path passed towatch()/add()are never ignored, so a missing path is still watched through its parent; their other contents are still filtered. A matcher is one of:- a string: an exact path. Relative strings are resolved against
cwd(or the process cwd). Globs are not supported; see upgrading for the replacement pattern. - a RegExp: tested against the whole path with forward slashes, on Windows too, e.g.
/(^|\/)\../for dotfiles or/\/node_modules\//. - a function
(path, stats?) => boolean: may be called twice per path, first with the path only, then with the path and itsfs.Stats, so guard stat-based checks withstats?.isFile(). - an object
{ path, recursive?: boolean }: an exact path, plus its subtree whenrecursiveis true.
- a string: an exact path. Relative strings are resolved against
ignoreInitial(default:false). Whentrue,add/addDirare not emitted for paths discovered during the initial scan (beforeready).followSymlinks(default:true). Whenfalse, symlinks are watched as themselves rather than followed; retargeting a link emitschange.cwd(no default). Base directory thatpathsare resolved against; emitted paths are relative to it.depth(default:undefined, unlimited). Maximum number of subdirectory levels to traverse.Infinitymeans unlimited.
Backend
backend(default:auto). Selects the filesystem observation backend:autouses native recursive watching on macOS and Windows and native per-directory watching elsewhere.nativeuses onefs.watchsubscription per directory.native-recursiveprefersfs.watch({ recursive: true })and falls back to per-directory watching where recursive watching is unavailable. A finitedepthalso uses per-directory watching so nothing beyond the requested tree is subscribed.pollinguses Chokidar's stat-based polling scheduler. Useful for network and other non-standard filesystems; uses more CPU.
pollingInterval(default:100) andpollingBinaryInterval(default:300, for recognized binary file extensions): polling periods in milliseconds, polling backend only. Polling compares size, modification time, existence, and (except on Windows) inode between polls; an in-place write that changes none of these is not detected.- Environment overrides:
CHOKIDAR_USEPOLLINGforces polling when truthy and disables it when falsy, even ifbackend: 'polling'is set in code;CHOKIDAR_INTERVALoverridespollingInterval. - Deprecated aliases kept for compatibility:
usePolling: truemeansbackend: 'polling';interval/binaryIntervalmeanpollingInterval/pollingBinaryInterval(the new spellings win when both are given).
Event timing
atomic(default:truewith native backends,falsewith polling; or a number of milliseconds). Editors that save through a temp file and rename produceunlinkthenadd; within the window (100 ms by default) Chokidar emits a singlechangeinstead. It also ignores common editor temp files (.swp/.swx,~backups, Sublime.subl*.tmp).awaitWriteFinish(default:false). By defaultadd/changefire as soon as a file appears or changes, which for large or chunked writes can be before the write is finished. Set totrue(or{ stabilityThreshold: 2000, pollInterval: 100 }) to holdadd/changeuntil the file size has stayed constant forstabilityThresholdms, checked everypollIntervalms. The right threshold depends on the OS and hardware: higher is safer and less responsive. Events from the initial scan are not held.alwaysStat(default:false). Always pass anfs.Statsobject withadd/addDir/change, issuing an extrastatwhen the backend did not provide one.
Errors and lifecycle
ignorePermissionErrors(default:false). Whentrue,EPERM/EACCESerrors from unreadable paths are suppressed instead of emitted.persistent(default:true). Whether the watcher keeps the process alive while it is watching.
Methods
.add(paths): start watching more files or directories (string or array)..unwatch(paths): stop watching files or directories (string or array). Synchronous; the paths stay ignored until they are.add()ed again..close(): async and terminal. Removes all listeners and stops all owned work. Repeated calls return the same Promise; once closing has started,.add()throws and a newFSWatcheris required..getWatched(): an object whose keys are the watched directories (absolute unlesscwdis set) and whose values are arrays of the entry names inside each..on(event, listener):FSWatcheris anEventEmitter; see events below.
Events
| Event | Listener arguments |
|---|---|
add, addDir, change | (path, stats?); stats when available, always with alwaysStat |
unlink, unlinkDir | (path) |
all | (event, path, stats?) for each of the five events above |
ready | none; the initial scan is complete |
error | (error) |
raw | (event, path, details) from the backend; unstable, use with care |
Troubleshooting
ENOSPC: System limit for number of file watchers reached(Linux): the inotify watch limit is exhausted. Raise it withecho fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p, or watch less: narrowpaths, addignored(for examplenode_modules), setdepth.EMFILE: too many open files: the process file-descriptor limit is exhausted. Watch less as above, raise the limit (ulimit -n 65536), or usebackend: 'polling', which holds no watch handles at the cost of CPU.fsevents-related install errors (WARN optional dep failed,fsevents is not a constructor) are solved by upgrading to v4+.
Changelog
- v6 (Oct 2026): complete rewrite; new fs.watch(recursive) backend on macos + windows; requires Node.js 22+
- v5 (Nov 2025): ESM-only; requires Node.js 20+
- v4 (Sep 2024): remove glob support & fsevents dependency, decrease dep count from 13 to 1; requires Node.js 14+
- v3 (Apr 2019): massive CPU & RAM consumption improvements; 17x decrease in pkg size + deps; requires Node.js 8.16+
- v2 (Dec 2017): posix-style globs; bugfixes
- v1 (Apr 2015): glob support, symlink support, tons of bugfixes; requires Node.js 0.8+
- v0.1 (Apr 2012): extracted from Brunch
Upgrading
Version 6 requires Node.js 22.22 or newer. An FSWatcher cannot be reopened after .close()
starts; construct a new watcher instead. Polling now defaults atomic to false, while an
explicit atomic value is preserved. Use pollingInterval and pollingBinaryInterval for
polling configuration; the v5 interval and binaryInterval spellings remain as deprecated
aliases.
Globs were removed in v4. To replicate them:
// v3
chokidar.watch('**/*.js');
chokidar.watch('./directory/**/*');
// v4+: filter instead
chokidar.watch('.', {
ignored: (path, stats) => stats?.isFile() && !path.endsWith('.js'), // only watch js files
});
chokidar.watch('./directory');
// or expand the glob yourself
import { glob } from 'node:fs/promises';
const watcher = chokidar.watch(await Array.fromAsync(glob('**/*.js')));
// unwatching
watcher.unwatch('**/*.js'); // v3
watcher.unwatch(await Array.fromAsync(glob('**/*.js'))); // v4+
Contributing
Run npm ci && npm run build && npm test (tests import the built files, so build first).
Internals and design requirements are documented in docs/architecture.md;
the cross-platform CI setup is in docs/vm-testing.md.
Also
Why was chokidar named this way? What's the meaning behind it?
Chowkidar is a transliteration of a Hindi word meaning 'watchman, gatekeeper', ΰ€ΰ₯ΰ€ΰ₯ΰ€¦ΰ€Ύΰ€°. This ultimately comes from Sanskrit _ ΰ€ΰ€€ΰ₯ΰ€·ΰ₯ΰ€_ (crossway, quadrangle, consisting-of-four). This word is also used in other languages like Urdu as (ΪΩΪ©ΫΨ―Ψ§Ψ±) which is widely used in Pakistan and India.
License
MIT (c) Paul Miller (https://paulmillr.com), see LICENSE file.