Unresolved behavior of nodemon’s batch restart logic on rapid file changes

Short answer

Yes — nodemon is designed to coalesce a burst of rapid file changes into a single restart, not to restart once per file event. When several files change in quick succession, nodemon treats them as one batch and restarts after the activity settles. The --delay option controls how long that settle window is: a new change arriving before the delay elapses effectively extends the quiet period, so the restart happens once, shortly after the last change in the burst.

One caveat up front: exact default delay values and option names vary by nodemon version, so verify against your installed version with nodemon --help or the config dump described below rather than trusting any hardcoded number.

Confirmed vs. likely explanation

Confirmed behavior: nodemon restarts after file-change activity settles, not on every raw filesystem event. The relevant controls are the restart delay, watched extensions and paths, ignore rules, and the legacy/polling watch mode.

Likely explanation for confusing symptoms: during an active burst, the quiet period keeps resetting, so nodemon looks unresponsive and then restarts once at the end. If you see multiple restarts for one logical save, the usual causes are not the debounce logic itself but:

• Editor atomic saves. Many editors write to a temp file and rename it over the original. This produces rename/create event sequences instead of a simple modify, and some watcher/OS combinations deliver these as separate events spaced far enough apart to fall outside the delay window.
• Filesystem delivery quirks. Docker bind mounts, VM shared folders, and network filesystems can drop, delay, or duplicate events, making batching look erratic.
• Self-triggering loops. Build artifacts, logs, or coverage output written inside watched paths trigger new changes after each restart, looking like broken batching.
• Slow child lifecycle. If your app takes time to exit or boot, restarts can appear skipped or stacked when the real issue is shutdown/startup overlap.

OS differences

Yes, there are real differences, but they live in the underlying watcher, not in nodemon's debounce logic. Linux (inotify), macOS (FSEvents), and Windows (ReadDirectoryChangesW) report events with different granularity and ordering, which is why the same editor save can coalesce cleanly on one OS and produce a double restart on another. The debounce window is what smooths this over — which is why a slightly larger --delay often "fixes" cross-OS inconsistency.

How to verify on your setup

1. Run with verbose output to see exactly what nodemon detects and when it restarts:

   nodemon --verbose your-app.js

   Watch whether a burst of touches produces multiple "files changed" lines but a single restart.
2. Generate a controlled burst:

   touch src/a.js src/b.js src/c.js

   One restart after the burst confirms batching is working.
3. Test the delay explicitly:

   nodemon --delay 2 your-app.js

   If double restarts disappear with a longer delay, the cause is event spacing (editor atomic saves or OS watcher behavior), not broken batching.
4. If you're on a bind mount, VM share, or network filesystem, try polling mode:

   nodemon --legacy-watch your-app.js

   This trades higher CPU/IO for reliable event delivery.
5. Exclude generated output so only real source edits trigger restarts:

   nodemon --ignore 'dist/*' --ignore 'logs/*' your-app.js

One detail that changes the recommendation

Where does your project live — local disk, Docker bind mount, VM shared folder, or network mount? If it's anything other than a local disk, the fix is almost certainly --legacy-watch plus ignore rules, not tuning --delay. On a local disk with an atomic-save editor, a modestly increased delay is the right lever.