chokidar
A minimal and efficient cross-platform file watching library for Node.js, improving upon native fs.watch.
What is chokidar?
Chokidar is a minimal and efficient cross-platform file watching library for Node.js that provides a reliable and normalized API for monitoring file and directory changes. It solves the inconsistencies and limitations of Node.js's native `fs.watch` and `fs.watchFile` by offering consistent event reporting across macOS, Windows, and Linux. The library is essential for build tools, development servers, and applications requiring real-time file updates.
Node.js developers building tools like bundlers, development servers, or any application that needs to react to file system changes in real time, especially those who need reliable cross-platform behavior. It is also suitable for developers working with network drives or editors that use atomic writes.
Developers choose Chokidar over native Node.js file watching because it normalizes events across operating systems, avoids duplicate events, and provides reliable filenames. Its unique selling points include support for atomic writes, chunked writes with configurable options, flexible filtering, and always-available recursive watching with performance optimizations that minimize CPU usage.
Overview
Minimal and efficient cross-platform file watching library
Use Cases
Best For
- Building development servers or hot-reload tools that need to watch for file changes across different operating systems.
- Creating build tools or bundlers that require reliable file system event handling without polling overhead by default.
- Monitoring large files or network drives where chunked writes or polling configurations are necessary.
- Implementing file synchronization or backup systems that need to ignore specific files or directories via flexible filtering.
- Developing IDE plugins or editor integrations that must handle atomic writes from text editors gracefully.
- Watching directories recursively with depth limits in applications like static site generators or CMS platforms.
Not Ideal For
- Projects monitoring tens of thousands of files simultaneously without OS-level tuning for file handle limits.
- Applications requiring built-in glob pattern matching without additional dependencies or custom code after v4.
- Environments where minimal memory and CPU usage is critical, as enabling polling for network drives can spike resource consumption.
- Real-time systems with strict latency requirements, since options like awaitWriteFinish introduce configurable delays for stability.
Pros & Cons
Pros
Normalizes file events across macOS, Windows, and Linux, ensuring consistent filenames and avoiding duplicates that plague native fs.watch, as highlighted in the README's 'Why?' section.
Handles atomic writes and chunked writes with options like awaitWriteFinish, essential for large files or editor integrations, with configurable thresholds for stability.
Allows ignoring files using functions, regex, or paths with support for symbolic links, enabling precise control over watched directories without extra setup.
Defaults to efficient fs.watch to minimize CPU usage, with polling as an opt-in for network drives or special cases, balancing speed and compatibility.
Cons
Can exhaust system file handles leading to EMFILE and ENOSP errors, requiring external fixes like graceful-fs or OS tuning, which adds operational complexity.
For network drives or edge cases, must use polling (usePolling: true), which significantly increases CPU and resource usage compared to the default mode.
Version 4 removed glob support and increased Node.js requirements, forcing migration work for existing projects, and v5 is ESM-only, limiting backward compatibility.
Frequently Asked Questions
Related Projects
fs-extraNode.js: extra methods for the fs object like copy(), remove(), mkdirs()
rimrafA `rm -rf` util for nodejs
globbyUser-friendly glob matching
delDelete files and directories
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.