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

> Minimal and efficient cross-platform file watching library used by thousands of Node.js tools including Vite, Webpack, and Nodemon.

## Install

Save as a script file and run:

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

## Quick Use
```bash
npm install chokidar
```
```js
const chokidar = require('chokidar');
const watcher = chokidar.watch('src', { persistent: true });
watcher.on('change', path => console.log(`Changed: ${path}`));
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-ae0c0640
Author: Script Depot