Chokidar
Efficient cross-platform file watching library for Node.js. Node.js's native fs.watch has platform inconsistencies and reliability issues — Chokidar normalizes them using native APIs (FSEvents on macOS, inotify on Linux) with polling fallback. Provides clean 'add', 'change', 'unlink' events with glob pattern filtering, debouncing, and ignore patterns.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
File watching exposes file system changes — ensure watched paths are appropriate and changes don't leak sensitive information. MIT licensed.
⚡ Reliability
Best When
You need reliable cross-platform file watching in Node.js development tools or automation scripts — Chokidar is the standard choice.
Avoid When
You're watching millions of files or need production-grade reliable file event delivery — native OS tools or message queues are more appropriate.
Use Cases
- • Watch source files for changes to trigger builds, tests, or restarts in development automation scripts
- • Implement file-based triggers in agent systems — process new files as they appear in a watched directory
- • Build hot-reload functionality in custom dev servers that need reliable file change detection
- • Watch configuration files for changes to reload agent behavior without restarts
- • Monitor file system for security purposes — detect unexpected file changes in sensitive directories
Not For
- • Production file monitoring at scale — use inotify/FSEvents directly or dedicated monitoring tools for production
- • Watching very large directory trees (millions of files) — memory and performance impact is significant
- • Replacing proper message queues — file watching is eventually consistent; use queues for reliable event delivery
Interface
Authentication
No authentication — file system library.
Pricing
MIT-licensed open source library.
Agent Metadata
Known Gotchas
- ⚠ Must add error event handler — unhandled 'error' events crash the Node.js process; chokidar.watch().on('error', handler) is required
- ⚠ awaitWriteFinish option needed for large file copies — without it, 'change' fires during write while file is incomplete; awaitWriteFinish waits for file to stop changing
- ⚠ Polling fallback for network file systems (NFS, Docker volumes) — native watchers don't work on NFS; set usePolling: true for network-mounted paths
- ⚠ Initial scan fires 'add' events for all existing files — use 'ready' event to distinguish initial scan from subsequent changes in your event handler
- ⚠ watching node_modules causes performance issues — always add 'ignored: /node_modules/' to prevent watching thousands of files
- ⚠ Chokidar v3 requires explicit .close() call when done — failing to close leaves file descriptor and inotify watch leaks; always close in cleanup handlers
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Chokidar.
Scores are editorial opinions as of 2026-03-06.