nodemon in Docker: legacy polling vs native file events for mounted volumes

Answer to the question

For a large bind‑mounted project that is shared across Windows, macOS and Linux hosts, the reliable, documented solution is to enable legacyWatch (the --legacy-watch flag). There is no flag that guarantees native file‑system events will fire correctly on all hosts when the source is mounted from a Windows or macOS machine, because Docker’s file‑system drivers translate events in a way that can lose or delay them.

Thus, the accepted trade‑off is: use legacy polling with an ignore list for node_modules and, if needed, a tuned polling interval. A starting interval of 2000 ms (the nodemon default) is safe; lowering to 1000 ms gives faster restarts with only modest CPU impact. Intervals below 500 ms tend to spike CPU usage in containers that already have many watchers.

Why legacy polling works reliably

• It checks file timestamps on a regular interval, independent of the underlying file‑system event mechanism.
• It works on networked, virtualised, or Docker‑for‑Windows/macOS mounts where native events are often lost.
• It can be combined with ignore patterns to reduce the number of files polled.

Configuring nodemon for Docker bind mounts

Place a nodemon.json in the project root (or use CLI flags). Example configuration:

{
  "watch": ["src"],
  "ignore": ["node_modules"],
  "legacyWatch": true,
  "watchDelay": 2000
}

Or run nodemon with flags:

nodemon --legacy-watch --watch-delay 2000 --watch src

Choosing a polling interval

1. Start with the default watchDelay of 2000 ms.
2. Edit a file from the host and confirm nodemon restarts within a second.
3. Check CPU usage in the container (e.g., docker stats or top). If the CPU stays below your threshold, you can reduce the interval.
4. Try watchDelay 1000 ms: responsiveness improves, CPU usually stays acceptable.
5. Only go below 500 ms if you need near‑real‑time feedback and your container has enough resources; monitor CPU closely.

Optional diagnostic question

Do you have a CPU usage limit you need to stay under when using polling? Knowing that threshold can help fine‑tune the interval.