chokidar

Chokidar is a battle-tested file watching library for Node.js that wraps the native fs.watch and fs.watchFile APIs and normalizes their notoriously inconsistent behavior into a clean, reliable event stream. It reports proper add, change, and unlink events across macOS, Linux, and Windows, handles recursive directory watching, symlinks, atomic saves, and chunked writes, and keeps CPU usage low by preferring event-based watching over polling.

Used in roughly 30 million repositories and depended on by tooling like webpack, Vite, and countless build systems, Chokidar is the de facto standard for watching the filesystem in the Node ecosystem. Version 5 is ESM-only, ships a single runtime dependency, and requires Node.js 20+.

What You Get

• A single chokidar.watch(paths, options) call that returns an FSWatcher emitting normalized add, addDir, change, unlink, unlinkDir, ready, and error events.
• Cross-platform consistency that hides the differences between macOS FSEvents, Linux inotify, and Windows watching backends.
• Recursive directory watching with configurable depth limits, symlink following, and path filtering via functions, regexes, or globs-free matchers.
• Write-safety options like awaitWriteFinish for chunked writes and atomic handling for editors that save via temp-file swaps.

Common Use Cases

• Powering hot-reload and live-rebuild in build tools, bundlers, and dev servers.
• Triggering test re-runs or linting when source files change during development.
• Syncing, uploading, or reprocessing assets automatically as files are added or modified.
• Watching configuration or content directories in long-running services and CLIs.

Under The Hood

Architecture — Chokidar is organized around two TypeScript modules. src/index.ts defines the public FSWatcher class (an EventEmitter subclass) plus the watch() factory, owning option normalization, path bookkeeping, throttling, the awaitWriteFinish/atomic write-safety logic, and directory traversal via the readdirp dependency. src/handler.ts holds NodeFsHandler, the low-level bridge that binds fs.watch and fs.watchFile per platform (branching on isWindows, isMacos, isLinux, isIBMi), deduplicates raw OS events, and calls back into the emitter with normalized event names. Events flow from the OS backend in the handler, through stat-based verification, into the throttled emitter surface consumers subscribe to.

Tech Stack — Written in TypeScript (99.7% of the codebase) targeting Node.js 20.19+, compiled with tsc to ESM output. It relies on Node core modules (node:fs, node:fs/promises, node:events, node:path, node:os) and exactly one runtime dependency, readdirp (^5), for recursive directory streaming. Dev tooling is minimal: Prettier for formatting, TypeScript 6, and tinyspy/upath for tests. The package is sideEffects: false and ESM-only.

Code Quality — The code is disciplined and well-typed, using exhaustive const-object event enums, explicit option types (BasicOpts, FSWInstanceOptions), and platform guards rather than ad-hoc checks. It ships a substantial test suite in src/index.test.ts (~110 test cases exercising add/change/unlink flows, symlinks, polling, and write-finish timing) run via node index.test.js. Naming is terse but consistent, and the single-dependency posture reflects deliberate attention to footprint.

API Design — The developer experience is exemplary: a one-liner chokidar.watch('.').on('all', cb) gets you started, while a single options object exposes every advanced knob (ignored, depth, usePolling, awaitWriteFinish, atomic, cwd). The chainable .on() emitter, clearly named events, and thorough README make the surface easy to learn and hard to misuse, which is why it has become the ecosystem default.