zerowatch

A modern, zero-dependency file watcher for Node.js.

• 🧭 Async-iterator first, with typed events and promise-based lifecycle.
• 📦 Zero runtime dependencies, ~25 KB minified, dual ESM + CommonJS.
• 🧰 Glob ignoring, debounce, batching, write-stability, polling.
• 🎯 Glob watch targets (watch("src/**/*.ts")) and fs.Stats on create/change events.

Install

npm install zerowatch

Usage

import { watch } from "zerowatch";

const watcher = watch("src", { recursive: true });

// Async iterator (primary API)
for await (const event of watcher) {
  console.log(`${event.type}: ${event.relativePath}`);
}

// …or typed events
watcher.on("create", (e) => console.log("created", e.relativePath));
watcher.on("move", (e) => console.log("moved", e.oldPath, "→", e.absolutePath));
watcher.on("error", (err) => console.error(err));

await watcher.ready(); // initial scan complete
await watcher.close(); // release handles, end the iterator

Common options: ignore, extensions, debounce, batch, gitignore, awaitWrite, usePolling. See docs/API.md for the full reference.

Benchmarks

Cold startup over a 5,000-file tree on macOS (run yarn bench):

| Watcher | Startup | Throughput | | ------------- | ---------- | ---------------- | | zerowatch | ~27 ms | ~8,700 events/s | | sane | ~31 ms | ~4,600 events/s | | chokidar | ~175 ms | ~18,000 events/s |

zerowatch has the fastest cold start of any scan-doing watcher — ~6× faster than chokidar — with zero dependencies; chokidar leads on sustained throughput (a deliberate ordering-correctness tradeoff).

Documentation

API reference · Migration guide · Examples · Changelog

License

MIT