chokidar vs watchpack vs gaze vs node-watch vs sane

File Watching Strategies in Node.js Build Tools

These five libraries handle file system monitoring in Node.js environments, enabling tools to react to changes in source code, assets, or configuration files. chokidar is the industry standard for cross-platform stability, wrapping native events with fallbacks. gaze offers built-in globbing but is older. node-watch provides a thin wrapper around native Node.js APIs. sane was designed for speed with multiple backends like Watchman. watchpack is optimized for dependency graphs, primarily used within the Webpack ecosystem.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package	Downloads	Stars	Size	Issues	Publish	License
Package	Downloads	Stars	Size	Issues	Publish	License
chokidar	214,589,901	12,246	82.1 kB	3	a year ago	MIT
watchpack	56,071,477	403	111 kB	9	5 hours ago	MIT
gaze	1,969,715	1,148	-	68	8 years ago	MIT
node-watch	0	340	26.1 kB	8	3 years ago	MIT
sane	0	386	-	34	5 years ago	MIT

File Watching Strategies in Node.js Build Tools

When building dev servers, bundlers, or task runners, your tool needs to know when files change. The five packages chokidar, gaze, node-watch, sane, and watchpack all solve this problem, but they differ in stability, API design, and intended use cases. Let's compare how they handle the core challenges of file watching.

🏗️ Initialization & Event Model

The way you start watching and listen for events varies significantly. Some use event emitters, while others use callbacks.

chokidar uses a class instance with an event emitter pattern. It is verbose but explicit.

// chokidar: Class-based with event listeners
const chokidar = require('chokidar');
const watcher = chokidar.watch('src/**/*.js');

watcher.on('add', path => console.log(`File added: ${path}`));
watcher.on('change', path => console.log(`File changed: ${path}`));

gaze also uses an event emitter but has a slightly different setup method.

// gaze: Event emitter with glob support
const gaze = require('gaze');

gaze('src/**/*.js', function(err, watcher) {
  watcher.on('changed', function(filepath) {
    console.log(`File changed: ${filepath}`);
  });
});

node-watch uses a function that returns a watcher with an event emitter.

// node-watch: Function-based return
const watch = require('node-watch');

const watcher = watch('src', { recursive: true });

watcher.on('update', function(event, filePath) {
  console.log(`File updated: ${filePath}`);
});

sane exports a watch function that accepts a callback for events.

// sane: Callback-based event handling
const sane = require('sane');

const watcher = sane.watch('src');

watcher.on('change', function(filePath, root, stat) {
  console.log(`File changed: ${filePath}`);
});

watchpack uses a class that aggregates events and delays them slightly for batching.

// watchpack: Batching events for bundlers
const Watchpack = require('watchpack');

const wp = new Watchpack({
  aggregateTimeout: 100
});

wp.watch([], ['src'], Date.now() + 1000);
wp.on('aggregated', function(changes, removals) {
  console.log(`Changes: ${changes}`);
});

🎯 Globbing & Pattern Matching

Developers rarely want to watch every single file. Pattern matching is critical for filtering noise.

chokidar accepts glob patterns directly in the watch method. It relies on micromatch internally.

// chokidar: Direct glob support
const watcher = chokidar.watch(['src/**/*.js', '!src/**/*.test.js'], {
  ignored: /node_modules/
});

gaze was built with globs as a first-class feature. It handles arrays of patterns natively.

// gaze: Native glob arrays
const watcher = gaze(['src/**/*.js', '!src/vendor/**']);

watcher.on('changed', function(filepath) {
  // Only matches defined patterns
});

node-watch supports globs but often requires the filter option for complex exclusion logic.

// node-watch: Filter function for logic
const watcher = watch('src', {
  recursive: true,
  filter: function(filePath, eventName) {
    return filePath.endsWith('.js') && !filePath.includes('test');
  }
});

sane supports patterns but is more focused on directory roots and ignore files like .gitignore.

// sane: Watch roots with ignore patterns
const watcher = sane.watch('src', {
  glob: ['**/*.js'],
  dot: false
});

watchpack does not focus on globs in the same way. It watches directories and tracks dependencies internally.

// watchpack: Directory based tracking
const wp = new Watchpack();

wp.watch([], ['src', 'config'], Date.now() + 1000);
// Tracks files inside these directories automatically

🔄 Recursive Watching & Performance

Watching entire folder trees efficiently is a common requirement. Performance varies based on how they handle native OS events.

chokidar enables recursion by default when using globs or directories. It pools file watchers to avoid hitting OS limits.

// chokidar: Recursive by default with dirs
const watcher = chokidar.watch('src', {
  persistent: true,
  depth: 5 // Limit recursion depth
});

gaze handles recursion well but can be heavier on memory due to its older architecture.

// gaze: Recursive globbing
const watcher = gaze('src/**/*');

watcher.on('added', function(filepath) {
  // Captures new files in subdirectories
});

node-watch requires an explicit flag to enable recursion.

// node-watch: Explicit recursive flag
const watcher = watch('src', {
  recursive: true,
  delay: 500
});

sane is optimized for speed and can use Watchman on macOS to reduce CPU usage significantly.

// sane: Optimized backend selection
const watcher = sane.watch('src', {
  useWatchman: true // If available
});

watchpack is tuned for large dependency trees typical in bundlers. It aggregates changes to prevent rebuild storms.

// watchpack: Aggregated updates
const wp = new Watchpack({
  aggregateTimeout: 300
});

wp.on('aggregated', function(changes) {
  // Receives one event for multiple file changes
});

⚠️ Error Handling & Stability

File watchers often crash when files are deleted or permissions change. Stability is key for long-running dev servers.

chokidar is known for handling permission errors and file deletions gracefully without crashing the process.

// chokidar: Error event handling
watcher.on('error', function(error) {
  console.error(`Watcher error: ${error}`);
});

gaze passes errors to the callback but may be less resilient on Windows file locks.

// gaze: Callback error handling
gaze('src', function(err, watcher) {
  if (err) {
    console.error(`Setup error: ${err}`);
    return;
  }
});

node-watch emits error events but relies heavily on the underlying Node.js fs stability.

// node-watch: Error listener
watcher.on('error', function(error) {
  console.error(`Native watch error: ${error}`);
});

sane handles backend failures by falling back to polling, ensuring continuity.

// sane: Fallback handling
watcher.on('error', function(error) {
  // Internal fallback logic triggers here
});

watchpack suppresses many low-level errors to keep the bundler running, exposing only critical issues.

// watchpack: Critical errors only
wp.on('error', function(error) {
  // Log critical watcher failures
});

🌐 Real-World Scenarios

Scenario 1: Hot Module Replacement (HMR)

You need to rebuild bundles instantly when source files change.

✅ Best choice: chokidar
Why? It is stable across OS platforms and integrates easily with dev servers.

// chokidar: HMR Setup
const watcher = chokidar.watch('src');
watcher.on('change', path => {
  devServer.reload(path);
});

Scenario 2: Task Automation (Sass/Less)

You want to compile styles when specific files change.

✅ Best choice: node-watch
Why? Lightweight and sufficient for simple directory watching.

// node-watch: Task Runner
const watcher = watch('styles', { recursive: true });
watcher.on('update', () => {
  runCompileTask();
});

Scenario 3: Large Monorepo Monitoring

You need to watch thousands of files with minimal CPU overhead.

✅ Best choice: sane
Why? Supports Watchman backend for high-performance monitoring.

// sane: Monorepo Watch
const watcher = sane.watch('packages', { useWatchman: true });

Scenario 4: Bundler Internals

You are writing a plugin for a module bundler.

✅ Best choice: watchpack
Why? Designed specifically for dependency graph tracking.

// watchpack: Dependency Tracking
const wp = new Watchpack();
wp.watch([], directories, startTime);

📊 Summary Table

Feature	`chokidar`	`gaze`	`node-watch`	`sane`	`watchpack`
API Style	Class + Events	Callback + Events	Function + Events	Function + Events	Class + Aggregation
Globbing	✅ Built-in	✅ Built-in	⚠️ Via Filter	⚠️ Basic	❌ Directory Focused
Recursion	✅ Default	✅ Default	⚠️ Explicit Flag	✅ Optimized	✅ Internal
Backends	fs.watch + Polling	fs.watch	fs.watch	Watchman + fs.watch	fs.watch + Polling
Best For	General Dev Tools	Legacy Systems	Simple Scripts	Large Repos	Bundler Internals

💡 Final Recommendation

For most frontend architects, chokidar is the correct default choice. It balances performance, stability, and ease of use better than the rest. It is the backbone of many popular tools for a reason.

Use node-watch if you need something smaller and simpler for internal scripts. Consider sane only if you have specific performance needs in a large monorepo environment. Avoid gaze for new work as it is legacy technology. Reserve watchpack for Webpack-specific extensions where dependency tracking is required.

Final Thought: File watching seems simple until you hit OS limits or permission errors. Choosing a mature library like chokidar saves you from debugging low-level file system issues so you can focus on your application logic.

How to Choose: chokidar vs watchpack vs gaze vs node-watch vs sane

chokidar:
Choose chokidar for most production applications requiring cross-platform reliability. It handles edge cases on macOS, Windows, and Linux better than native solutions. It is the safest bet for build tools, dev servers, and any system where missing a file change is not an option.
watchpack:
Choose watchpack if you are building a plugin for Webpack or need to track dependency graphs rather than raw file events. It is specialized for bundler internals and is not intended as a general-purpose file watcher for application logic.
gaze:
Choose gaze only if you are maintaining legacy systems that already depend on it. It is not recommended for new projects due to age and less active maintenance compared to modern alternatives. Its built-in globbing is convenient but available elsewhere now.
node-watch:
Choose node-watch if you want a lightweight dependency with no native bindings or complex fallbacks. It is suitable for simple scripts on stable environments where you do not need the extra stability layers that chokidar provides.
sane:
Choose sane if you are integrating with tools that specifically expect its API, such as older versions of Jest. It supports multiple backends like Watchman for performance, but chokidar has largely superseded it for general use cases.

Popular Comparisons

chokidar

watchpack

gaze

node-watch

sane

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 atomic option
- Some file editors use them
Chunked writes are supported, using awaitWriteFinish option
- 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

ignored function, 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 the fs.Stats object of that path).
ignoreInitial (default: false). If set to false then add/addDir events are also emitted for matching paths while instantiating the watching as chokidar discovers these file paths (before the ready event).
followSymlinks (default: true). When false, 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 watch paths are 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 to false. It is typically necessary to set this to true to successfully watch files over a network, and it may be necessary to successfully watch files in other non-standard situations. Setting to true explicitly on MacOS overrides the useFsEvents default. 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 the fs.Stats object that may get passed with add, addDir, and change events, set this to true to 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, the add event will fire when a file first appears on disk, before the entire file has been written. Furthermore, in some cases some change events 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. Setting awaitWriteFinish to true (or a truthy value) will poll file size, holding its add and change events 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.awaitWriteFinish can 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 to EPERM or EACCES with this set to true, the errors will be suppressed silently.
atomic (default: true if useFsEvents and usePolling are false). 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 a change event rather than unlink then add. If the default of 100 ms does not work well for you, you can override it by setting atomic to 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. Additionally all is available which gets emitted with the underlying event name and path for every event other than ready, raw, and error. raw is 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 with await to ensure bugs don't happen.
.getWatched(): Returns an object representing all the paths on the file system being watched by this FSWatcher instance. The object's keys are all the directories (using absolute paths unless the cwd option 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 shell
Error: 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 fs module 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.
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-intensive fs.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.

File Watching Strategies in Node.js Build Tools

Npm Package Weekly Downloads Trend

Github Stars Ranking

Stat Detail

File Watching Strategies in Node.js Build Tools

🏗️ Initialization & Event Model

🎯 Globbing & Pattern Matching

🔄 Recursive Watching & Performance

⚠️ Error Handling & Stability

🌐 Real-World Scenarios

Scenario 1: Hot Module Replacement (HMR)

Scenario 2: Task Automation (Sass/Less)

Scenario 3: Large Monorepo Monitoring

Scenario 4: Bundler Internals

📊 Summary Table

💡 Final Recommendation

How to Choose: chokidar vs watchpack vs gaze vs node-watch vs sane

Popular Comparisons

Similar Npm Packages to chokidar

Similar Npm Packages to watchpack

Similar Npm Packages to gaze

Similar Npm Packages to node-watch

Similar Npm Packages to sane

README for chokidar

Chokidar

Why?

Getting started

Persistence

Path filtering

Performance

Errors

Methods & Events

CLI

Troubleshooting

Changelog

Upgrading

Also

License