chokidar

Minimal and efficient cross-platform file watching library

weekly downloads112.8M

versionv5.0.0

licenseMIT

categorytoolchain

fswatchwatchFilewatcherwatchingfilefsevents

Overview

Chokidar is a production-grade file watching library that monitors files and directories for changes, additions, and deletions across all major platforms. It solves critical limitations in Node.js's native fs.watch and fs.watchFile APIs, including inconsistent event handling, lack of recursive watching on some platforms, duplicate events, and high CPU usage from polling. With over 112 million weekly downloads, it powers major tools like Webpack, VS Code, Vite, and Gulp.

The library provides a unified API that uses native OS primitives where available—fsevents on macOS via N-API, ReadDirectoryChangesW on Windows, and inotify on Linux—falling back to polling only when necessary. This approach delivers both performance and reliability without the platform-specific quirks that plague native Node.js watchers.

Version 5.0.0 represents a major modernization effort: rewritten in TypeScript, reduced from 13 dependencies to just one (readdirp), and eliminated bundled glob support for a leaner package. The v3 release achieved a 17x smaller footprint and 4.9x faster installation compared to v2, while maintaining the same feature set. Chokidar handles edge cases like atomic writes (common in text editors that save by renaming temp files), symbolic links, and chunked writes for large files—all scenarios where native watchers fail or produce confusing events.

The library is designed for intermediate to advanced developers building CLIs, development servers, build tools, or any application requiring real-time file system awareness. It requires Node.js 14+ and supports both CommonJS and ES modules with full TypeScript definitions.

Quick Start

typescript

import chokidar from 'chokidar';
import { execSync } from 'child_process';

const watcher = chokidar.watch('src/**/*.ts', {
  ignored: /(^|[\/\\])\../, // ignore dotfiles
  persistent: true,
  ignoreInitial: true,
  awaitWriteFinish: {
    stabilityThreshold: 500,
    pollInterval: 100
  },
  atomic: true
});

watcher
  .on('add', path => console.log(`File ${path} has been added`))
  .on('change', path => {
    console.log(`File ${path} changed, rebuilding...`);
    try {
      execSync('npm run build', { stdio: 'inherit' });
      console.log('Build completed successfully');
    } catch (error) {
      console.error('Build failed:', error.message);
    }
  })
  .on('unlink', path => console.log(`File ${path} removed`))
  .on('error', error => console.error('Watcher error:', error))
  .on('ready', () => console.log('Initial scan complete. Watching for changes...'));

// Dynamically add more paths
watcher.add('tests/**/*.test.ts');

// Graceful shutdown
process.on('SIGINT', async () => {
  console.log('\nStopping watcher...');
  await watcher.close();
  process.exit(0);
});

Use Cases

Development servers and hot reload systems: Tools like Webpack Dev Server and Vite use chokidar to detect source file changes and trigger rebuilds or hot module replacement. The atomic write handling ensures that partial file writes don't trigger premature reloads.

Build automation and task runners: Gulp, Grunt, and custom build scripts watch source directories to automatically compile Sass, transpile TypeScript, or optimize images when files change. Chokidar's recursive watching with depth limits allows monitoring entire project trees efficiently.

Backup and synchronization tools: File sync applications monitor directories to replicate changes to cloud storage or remote servers. The awaitWriteFinish option ensures large files are fully written before processing begins, preventing corrupt transfers.

Code editors and IDEs: VS Code and other editors use chokidar to detect external file modifications, prompting users to reload changed files. The ignored patterns feature excludes .git, node_modules, and other non-source directories from monitoring.

Test runners with watch mode: Jest, Mocha, and Vitest employ chokidar to re-run tests when source or test files change, providing immediate feedback during development. The ability to dynamically add or remove watched paths supports incremental test execution patterns.

Pros & Cons

Pros

+Cross-platform consistency with native performance using fsevents (macOS), inotify (Linux), and ReadDirectoryChangesW (Windows)
+Handles atomic writes, symbolic links, and chunked file writes that break native fs.watch implementations
+Mature and battle-tested with 112M+ weekly downloads, used by Webpack, VS Code, Vite, and other production tools
+Minimal dependencies (only readdirp as of v5) with TypeScript definitions and modern ES module support
+Rich event filtering with regex, functions, and glob patterns plus dynamic add/unwatch capabilities

Cons

−Adds ~352KB to package size versus zero-dependency native fs.watch for simple use cases
−Recursive watching on network drives or very large directories can still consume significant resources
−Breaking changes between major versions (v3, v4, v5) require migration effort for long-lived projects
−Polling fallback on unsupported file systems increases CPU usage compared to native event-driven watching
−Overkill for single-file watches or scenarios where platform-specific behavior is acceptable

Comparisons

chokidar vs fast-glob

toolchain

Install

bash

npm install chokidar

bash

pnpm add chokidar

bash

bun add chokidar

Overview

Quick Start

typescript

import chokidar from 'chokidar';
import { execSync } from 'child_process';

const watcher = chokidar.watch('src/**/*.ts', {
  ignored: /(^|[\/\\])\../, // ignore dotfiles
  persistent: true,
  ignoreInitial: true,
  awaitWriteFinish: {
    stabilityThreshold: 500,
    pollInterval: 100
  },
  atomic: true
});

watcher
  .on('add', path => console.log(`File ${path} has been added`))
  .on('change', path => {
    console.log(`File ${path} changed, rebuilding...`);
    try {
      execSync('npm run build', { stdio: 'inherit' });
      console.log('Build completed successfully');
    } catch (error) {
      console.error('Build failed:', error.message);
    }
  })
  .on('unlink', path => console.log(`File ${path} removed`))
  .on('error', error => console.error('Watcher error:', error))
  .on('ready', () => console.log('Initial scan complete. Watching for changes...'));

// Dynamically add more paths
watcher.add('tests/**/*.test.ts');

// Graceful shutdown
process.on('SIGINT', async () => {
  console.log('\nStopping watcher...');
  await watcher.close();
  process.exit(0);
});

Use Cases

Pros & Cons

Pros

+Cross-platform consistency with native performance using fsevents (macOS), inotify (Linux), and ReadDirectoryChangesW (Windows)
+Handles atomic writes, symbolic links, and chunked file writes that break native fs.watch implementations
+Mature and battle-tested with 112M+ weekly downloads, used by Webpack, VS Code, Vite, and other production tools
+Minimal dependencies (only readdirp as of v5) with TypeScript definitions and modern ES module support
+Rich event filtering with regex, functions, and glob patterns plus dynamic add/unwatch capabilities

Cons

−Adds ~352KB to package size versus zero-dependency native fs.watch for simple use cases
−Recursive watching on network drives or very large directories can still consume significant resources
−Breaking changes between major versions (v3, v4, v5) require migration effort for long-lived projects
−Polling fallback on unsupported file systems increases CPU usage compared to native event-driven watching
−Overkill for single-file watches or scenarios where platform-specific behavior is acceptable