Nodemon restarts inconsistently after file changes: chokidar default vs --legacy watcher behavior

Answer

Standardize on the chokidar default watcher and tune its delay and polling options; reserve --legacy only for cases where you have confirmed missed changes that chokidar's fallback does not fix, since the flag may not survive future major releases.

Confirmed facts

• Since nodemon v1.0, chokidar is the default watcher; --legacy forces the older Node fs.watch implementation.
• Chokidar debounces rapid changes and waits roughly the --delay interval (about 100 ms by default) before restarting, collapsing a burst of saves into one restart.
• Legacy fs.watch forwards events immediately, which can produce multiple restart notifications for a single edit.
• On Docker bind-mounted volumes, fs.watch events may never propagate, causing silent missed changes; chokidar detects watcher failure and falls back to polling, trading CPU for reliability.
• On case-insensitive filesystems (default macOS, Windows), chokidar may treat File.js and file.js as distinct paths, which can cause duplicate restarts unless paths are normalized.

Likely explanation

Restart timing differences come from chokidar's debounce delay versus fs.watch's immediate forwarding. Missed changes on shared volumes are more likely with fs.watch because the kernel does not reliably emit events for bind-mounted files; chokidar's polling fallback exists precisely to cover that gap.

Verification and configuration

1. Confirm which watcher is active at runtime using debug output:

DEBUG=nodemon* nodemon your-app.js            # expect a line containing "watch: chokidar"
DEBUG=nodemon* nodemon --legacy your-app.js   # expect a line containing "watch: legacy"

2. Measure restart latency: touch a watched file and time the "restarting due to changes" message. Legacy should be near-instant; chokidar should reflect the configured delay.
3. For Docker bind mounts, prefer explicit polling over legacy mode:

nodemon --pollingInterval 500 your-app.js

4. Tune debounce to your editing workflow:

nodemon --delay 150 your-app.js

One caveat: polling raises CPU usage on large watch trees, so keep --pollingInterval conservative and use --ignore for directories like node_modules and build output. If inconsistent restarts persist after these settings, the missing diagnostic is the exact mount type (e.g., Docker Desktop gRPC FUSE vs. virtiofs vs. plain Linux bind mount), since that determines whether events can propagate at all.