Chokidar — Efficient Cross-Platform File Watching for Node.js

Introduction

Chokidar wraps Node.js fs.watch and fs.watchFile behind a normalized, cross-platform API that handles the many inconsistencies and edge cases of native file system events on macOS, Linux, and Windows. It is one of the most depended-upon packages in the npm ecosystem, used internally by Vite, Webpack, Karma, PM2, Nodemon, and many other tools.

What Chokidar Does

• Watches files and directories for add, change, and unlink events with a single consistent API
• Handles atomic writes, symlinks, and rename operations that trip up raw fs.watch
• Supports glob patterns, ignored paths, and per-OS tuning options
• Provides an awaitWriteFinish option that waits for writes to stabilize before emitting events
• Emits ready, error, and raw events for fine-grained lifecycle control

Architecture Overview

Chokidar v4 is a minimal rewrite that delegates to the native fs.watch recursive option on macOS and Windows. On Linux, it walks the directory tree and attaches inotify watchers per directory. A throttle layer deduplicates rapid-fire events, and the awaitWriteFinish module polls file size stability before surfacing a change event. The library exposes an EventEmitter-based watcher object that callers subscribe to.

Self-Hosting & Configuration

• Install via npm install chokidar or yarn add chokidar
• Pass a glob or array of paths to chokidar.watch(paths, options)
• Set ignored to exclude node_modules or build artifacts
• Enable awaitWriteFinish: { stabilityThreshold: 500 } for large files
• Use depth to limit recursive directory traversal

Key Features

• Works identically on macOS, Linux, and Windows without platform-specific code
• Extremely small footprint in v4 with zero native dependencies
• Handles edge cases like editors that write to temp files then rename
• Supports both ESM and CommonJS imports
• Battle-tested by the largest build tools in the Node.js ecosystem

Comparison with Similar Tools

• fs.watch — built-in but unreliable across platforms; Chokidar normalizes its quirks
• watchman (Meta) — powerful but requires a separate daemon; Chokidar is in-process
• nodemon — uses Chokidar internally, adds restart logic on top
• paulmillr/readdirp — directory traversal only, no watching

FAQ

Q: Does Chokidar v4 still use fsevents on macOS? A: v4 relies on Node.js native fs.watch with recursive support, removing the need for the optional fsevents binding.

Q: How do I watch only specific file types? A: Pass a glob pattern like src/**/*.ts or use the ignored option to filter unwanted extensions.

Q: Can Chokidar handle thousands of files? A: Yes. On Linux it uses one inotify watcher per directory, not per file, so large trees are efficient.

Q: Is Chokidar suitable for production servers? A: It is designed for development tooling. For production file monitoring consider inotifywait or similar OS-level tools.

Sources

• https://github.com/paulmillr/chokidar
• https://www.npmjs.com/package/chokidar