Does nodemon --delay guarantee one restart per batch of rapid file edits?

Direct answer

Yes. When --delay is set to a non-zero value, nodemon starts a timer on the first file-change event it receives. Any additional change events that arrive before that timer expires are absorbed into the same pending restart — the timer does not reset, and no duplicate restarts are scheduled. The process restarts exactly once when the original delay elapses.

How the coalescing works

• The delay timer is created in nodemon's JavaScript layer (wrapping chokidar), not in the OS-level watcher (inotify, FSEvents, ReadDirectoryChangesW).
• On the first event, a setTimeout is scheduled for the configured milliseconds (default 50 ms, configurable via --delay <ms>).
• While that timeout is pending, subsequent change, add, or unlink events from the watcher are ignored for restart purposes — they do not create new timers or extend the existing one.
• When the timeout fires, nodemon kills the child process (if running) and spawns a fresh one.

Why this matters for editors

Atomic saves (write-to-temp-then-rename) typically emit a burst of 2–3 events (unlink, add, change) within a few milliseconds. With --delay 50 (or any value ≥ 50 ms) those events fall inside the same window and produce a single restart. Setting --delay 0 or --delay 1 defeats the coalescing because the timer can expire between OS event batches.

Version and configuration caveats

• nodemon ≥ 2.0: coalescing behavior described above is stable across Linux, macOS, and Windows.
• nodemon < 1.18: a bug caused each event to reset the timer, leading to duplicate restarts. Upgrade to avoid this.
• --legacy-watch (polling mode): the polling interval may deliver events in separate polls; if the poll interval exceeds your --delay value, coalescing can break.
• Custom watcher options (awaitWriteFinish, ignoreInitial via nodemon.json or --watch) can interact with --delay; test your specific config.
• Multiple nodemon instances watching overlapping directories each maintain independent timers and will restart independently.

Quick verification

1. Create test.js:

   console.log('PID', process.pid, 'started at', new Date().toISOString());

2. Run nodemon --delay 100 test.js.
3. In another terminal, fire rapid touches:

   for i in {1..10}; do touch test.js; done

4. Observe the console: only one new PID line should appear ~100 ms after the first touch.
5. Repeat with nodemon --delay 0 test.js to see multiple restarts (confirms coalescing depends on a non-zero delay).
6. Check version: nodemon --version (should be ≥ 2.0).

Summary

--delay provides a true debounce: one timer, one restart, no reset. Use ≥ 50 ms for reliable coalescing with modern editors and atomic saves. Verify with the steps above if your setup behaves differently.