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?
There are many reasons to prefer Chokidar to raw fs.watch / fs.watchFile in 2026:
- Events are properly reported
- macOS events report filenames
- events are not reported twice
- changes are reported as add / change / unlink instead of useless
rename
- Atomic writes are supported, using
atomicoption- Some file editors use them
- Chunked writes are supported, using
awaitWriteFinishoption- Large files are commonly written in chunks
- File / dir filtering is supported
- Symbolic links are supported
- Recursive watching is always supported, instead of partial when using raw events
- Includes a way to limit recursion depth
Chokidar relies on the Node.js core fs module, but when using
fs.watch and fs.watchFile for watching, it normalizes the events it
receives, often checking for truth by getting file stats and/or dir contents.
The fs.watch-based implementation is the default, which
avoids polling and keeps CPU usage down. Be advised that chokidar will initiate
watchers recursively for everything within scope of the paths that have been
specified, so be judicious about not wasting system resources by watching much
more than needed. For some cases, fs.watchFile, which utilizes polling and uses more resources, is used.
Made for Brunch in 2012, it is now used in ~30 million repositories and has proven itself in production environments.
- Nov 2025 update: v5 is out. Makes package ESM-only and increases minimum node.js requirement to v20.
- Sep 2024 update: v4 is out! It decreases dependency count from 13 to 1, removes support for globs, adds support for ESM / Common.js modules, and bumps minimum node.js version from v8 to v14. Check out upgrading.
Getting started
Install with npm:
npm install chokidar
Use it in your code:
import chokidar from 'chokidar';
// One-liner for current directory
chokidar.watch('.').on('all', (event, path) => {
console.log(event, path);
});
// Extended options
// ----------------
// Initialize watcher.
const watcher = chokidar.watch('file, dir, or array', {
ignored: (path, stats) => stats?.isFile() && !path.endsWith('.js'), // only watch js files
persistent: true,
});
// Something to use when events are received.
const log = console.log.bind(console);
// Add event listeners.
watcher
.on('add', (path) => log(`File ${path} has been added`))
.on('change', (path) => log(`File ${path} has been changed`))
.on('unlink', (path) => log(`File ${path} has been removed`));
// More possible events.
watcher
.on('addDir', (path) => log(`Directory ${path} has been added`))
.on('unlinkDir', (path) => log(`Directory ${path} has been removed`))
.on('error', (error) => log(`Watcher error: ${error}`))
.on('ready', () => log('Initial scan complete. Ready for changes'))
.on('raw', (event, path, details) => {
// internal
log('Raw event info:', event, path, details);
});
// 'add', 'addDir' and 'change' events also receive stat() results as second
// argument when available: https://nodejs.org/api/fs.html#fs_class_fs_stats
watcher.on('change', (path, stats) => {
if (stats) console.log(`File ${path} changed size to ${stats.size}`);
});
// Watch new files.
watcher.add('new-file');
watcher.add(['new-file-2', 'new-file-3']);
// Get list of actual paths being watched on the filesystem
let watchedPaths = watcher.getWatched();
// Un-watch some files.
await watcher.unwatch('new-file');
// Stop watching. The method is async!
await watcher.close().then(() => console.log('closed'));
// Full list of options. See below for descriptions.
// Do not use this example!
chokidar.watch('file', {
persistent: true,
// ignore .txt files
ignored: (file) => file.endsWith('.txt'),
// watch only .txt files
// ignored: (file, _stats) => _stats?.isFile() && !file.endsWith('.txt'),
awaitWriteFinish: true, // emit single event when chunked writes are completed
atomic: true, // emit proper events when "atomic writes" (mv _tmp file) are used
// The options also allow specifying custom intervals in ms
// awaitWriteFinish: {
// stabilityThreshold: 2000,
// pollInterval: 100
// },
// atomic: 100,
interval: 100,
binaryInterval: 300,
cwd: '.',
depth: 99,
followSymlinks: true,
ignoreInitial: false,
ignorePermissionErrors: false,
usePolling: false,
alwaysStat: false,
});
chokidar.watch(paths, [options])
paths(string or array of strings). Paths to files, dirs to be watched recursively.options(object) Options object as defined below:
Persistence
persistent(default:true). Indicates whether the process should continue to run as long as files are being watched.
Path filtering
ignoredfunction, regex, or path. Defines files/paths to be ignored. The whole relative or absolute path is tested, not just filename. If a function with two arguments is provided, it gets called twice per path - once with a single argument (the path), second time with two arguments (the path and thefs.Statsobject of that path).ignoreInitial(default:false). If set tofalsethenadd/addDirevents are also emitted for matching paths while instantiating the watching as chokidar discovers these file paths (before thereadyevent).followSymlinks(default:true). Whenfalse, only the symlinks themselves will be watched for changes instead of following the link references and bubbling events through the link's path.cwd(no default). The base directory from which watchpathsare to be derived. Paths emitted with events will be relative to this.
Performance
usePolling(default:false). Whether to use fs.watchFile (backed by polling), or fs.watch. If polling leads to high CPU utilization, consider setting this tofalse. It is typically necessary to set this totrueto successfully watch files over a network, and it may be necessary to successfully watch files in other non-standard situations. Setting totrueexplicitly on MacOS overrides theuseFsEventsdefault. You may also set the CHOKIDAR_USEPOLLING env variable to true (1) or false (0) in order to override this option.- Polling-specific settings (effective when
usePolling: true)interval(default:100). Interval of file system polling, in milliseconds. You may also set the CHOKIDAR_INTERVAL env variable to override this option.binaryInterval(default:300). Interval of file system polling for binary files. (see list of binary extensions)
alwaysStat(default:false). If relying upon thefs.Statsobject that may get passed withadd,addDir, andchangeevents, set this totrueto ensure it is provided even in cases where it wasn't already available from the underlying watch events.depth(default:undefined). If set, limits how many levels of subdirectories will be traversed.awaitWriteFinish(default:false). By default, theaddevent will fire when a file first appears on disk, before the entire file has been written. Furthermore, in some cases somechangeevents will be emitted while the file is being written. In some cases, especially when watching for large files there will be a need to wait for the write operation to finish before responding to a file creation or modification. SettingawaitWriteFinishtotrue(or a truthy value) will poll file size, holding itsaddandchangeevents until the size does not change for a configurable amount of time. The appropriate duration setting is heavily dependent on the OS and hardware. For accurate detection this parameter should be relatively high, making file watching much less responsive. Use with caution.options.awaitWriteFinishcan be set to an object in order to adjust timing params:awaitWriteFinish.stabilityThreshold(default: 2000). Amount of time in milliseconds for a file size to remain constant before emitting its event.awaitWriteFinish.pollInterval(default: 100). File size polling interval, in milliseconds.
Errors
ignorePermissionErrors(default:false). Indicates whether to watch files that don't have read permissions if possible. If watching fails due toEPERMorEACCESwith this set totrue, the errors will be suppressed silently.atomic(default:trueifuseFsEventsandusePollingarefalse). Automatically filters out artifacts that occur when using editors that use "atomic writes" instead of writing directly to the source file. If a file is re-added within 100 ms of being deleted, Chokidar emits achangeevent rather thanunlinkthenadd. If the default of 100 ms does not work well for you, you can override it by settingatomicto a custom value, in milliseconds.
Methods & Events
chokidar.watch() produces an instance of FSWatcher. Methods of FSWatcher:
.add(path / paths): Add files, directories for tracking. Takes an array of strings or just one string..on(event, callback): Listen for an FS event. Available events:add,addDir,change,unlink,unlinkDir,ready,raw,error. Additionallyallis available which gets emitted with the underlying event name and path for every event other thanready,raw, anderror.rawis internal, use it carefully..unwatch(path / paths): Stop watching files or directories. Takes an array of strings or just one string..close(): async Removes all listeners from watched files. Asynchronous, returns Promise. Use withawaitto ensure bugs don't happen..getWatched(): Returns an object representing all the paths on the file system being watched by thisFSWatcherinstance. The object's keys are all the directories (using absolute paths unless thecwdoption was used), and the values are arrays of the names of the items contained in each directory.
CLI
Check out third party chokidar-cli, which allows to execute a command on each change, or get a stdio stream of change events.
Troubleshooting
Sometimes, Chokidar runs out of file handles, causing EMFILE and ENOSP errors:
bash: cannot set terminal process group (-1): Inappropriate ioctl for device bash: no job control in this shellError: watch /home/ ENOSPC
There are two things that can cause it.
- Exhausted file handles for generic fs operations
- Can be solved by using graceful-fs,
which can monkey-patch native
fsmodule used by chokidar:let fs = require('fs'); let grfs = require('graceful-fs'); grfs.gracefulify(fs); - Can also be solved by tuning OS:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p.
- Can be solved by using graceful-fs,
which can monkey-patch native
- Exhausted file handles for
fs.watch- Can't seem to be solved by graceful-fs or OS tuning
- It's possible to start using
usePolling: true, which will switch backend to resource-intensivefs.watchFile
All fsevents-related issues (WARN optional dep failed, fsevents is not a constructor) are solved by upgrading to v4+.
Changelog
- v4 (Sep 2024): remove glob support and bundled fsevents. Decrease dependency count from 13 to 1. Rewrite in typescript. Bumps minimum node.js requirement to v14+
- v3 (Apr 2019): massive CPU & RAM consumption improvements; reduces deps / package size by a factor of 17x and bumps Node.js requirement to v8.16+.
- v2 (Dec 2017): globs are now posix-style-only. Tons of bugfixes.
- v1 (Apr 2015): glob support, symlink support, tons of bugfixes. Node 0.8+ is supported
- v0.1 (Apr 2012): Initial release, extracted from Brunch
Upgrading
If you've used globs before and want do replicate the functionality with v4:
// v3
chok.watch('**/*.js');
chok.watch('./directory/**/*');
// v4
chok.watch('.', {
ignored: (path, stats) => stats?.isFile() && !path.endsWith('.js'), // only watch js files
});
chok.watch('./directory');
// other way
import { glob } from 'node:fs/promises';
const watcher = watch(await Array.fromAsync(glob('**/*.js')));
// unwatching
// v3
chok.unwatch('**/*.js');
// v4
chok.unwatch(await Array.fromAsync(glob('**/*.js')));
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.