Taming Nodemon Restart Thrash with Delay and Ignore Config

The problem: restarts that happen too often

When you are editing multiple files in a Node.js project—running a bulk search‑replace, formatting with Prettier, or watching a transpiler output—nodemon’s default behavior can cause a restart for every single change. On large projects or when using Docker volumes that emit many fs events, this leads to noticeable CPU spikes, delayed feedback, and sometimes exceeds the system’s file‑descriptor limit.

The useful takeaway is that nodemon provides three complementary knobs—--delay, per‑project ignore/watch patterns in nodemon.json, and the legacyWatch flag—that let you tune when a restart actually occurs.

How nodemon decides to restart

By default nodemon watches files with extensions .js, .mjs, and .json in the current directory and subdirectories, using the OS’s fs.watch API. Each time a watched file changes, it immediately spawns a new Node process.

Two situations break this model:

• Docker bind‑mounts or network file systems where fs.watch events are unreliable or missing.
• High‑frequency changes (e.g., saving 20 files at once) that you only want to treat as a single logical edit.

Nodemon addresses both with configurable options.

Configuring nodemon via nodemon.json

Create a nodemon.json in the project root. The file is JSON and can contain the following keys:

• ignore – an array of glob patterns that nodemon will not watch.
• watch – explicit directories to watch; overrides the default recursive scan.
• ext – comma‑separated list of file extensions to consider.
• legacyWatch – set to true to fall back to polling‑based watching when fs.watch fails.
• delay – milliseconds to wait after the last change before restarting (equivalent to the CLI --delay).

Example configuration that works well for a typical Express app inside Docker:

{
  "watch": ["src"],
  "ignore": ["node_modules/**", "logs/**", "*.test.js"],
  "ext": "js,json",
  "delay": "2500",
  "legacyWatch": true
}

What this does:

1. Only files under src/ trigger a restart.
2. Changes in node_modules, log files, or test files are ignored.
3. If a change occurs, nodemon waits 2.5 seconds after the last edit before restarting, bundling rapid saves into a single restart.
4. When running inside a Docker volume where fs.watch may miss events, the polling fallback ensures changes are still detected.

Using the CLI flags directly

If you prefer not to maintain a JSON file, the same behavior can be invoked from the command line:

nodemon \
  --watch src \
  --ignore node_modules/ \
  --ignore logs/ \
  --ext js,json \
  --delay 2500 \
  --legacy-watch \
  --exec "node src/index.js"

The --exec flag shows nodemon’s ability to run non‑Node scripts; here we simply launch the Node entry point, but you could replace it with "ts-node src/index.ts" or any build tool.

Required permissions: none beyond normal user rights to read the watched files and execute the Node binary. Running nodemon inside a container requires the container to have fsnotify access to the mounted volume; the legacyWatch flag mitigates cases where the mount restricts inotify.

Trade‑offs and limitations

Introducing a delay means that genuine errors in a file will not be reflected until the delay period elapses, which can slow down the feedback loop when you are intentionally making a single change and want immediate verification. Adjust --delay to a lower value (e.g., 500 ms) for tight loops, or keep it higher only during bulk‑edit sessions.

Using legacyWatch replaces the efficient fs.watch with a polling mechanism that checks the file system every few hundred milliseconds. This can increase CPU usage slightly, especially with many large files, but it is usually far less costly than the thrash caused by missed events leading to manual restarts.

Finally, nodemon is a development tool. Running it in production bypasses the process‑manager’s supervision (e.g., PM2, systemd) and can cause unexpected downtime if a file change occurs accidentally. Always reserve nodemon for local development, CI preview builds, or ephemeral environments.

Actionable closing

To verify that your configuration works as expected:

1. Start nodemon with your chosen config: nodemon --config nodemon.json (or the full CLI version).
2. Make a change to a watched file (e.g., edit src/index.js). Note the timestamp in the console when the process restarts.
3. Make several rapid changes to different watched files within a short window (e.g., save five files in succession). You should see only a single restart after the delay period expires.
4. Edit an ignored file (e.g., touch logs/debug.log) and confirm that no restart occurs.

If you see restarts happening too frequently, increase the delay value or add more specific ignore patterns. If changes are not triggering a restart at all, ensure legacyWatch is enabled when using Docker or NFS mounts, and verify that the watch paths correctly point to your source directory.

By tuning these three knobs—ignore patterns, delay, and legacy watch—you can keep nodemon responsive without the CPU‑thrashing that often accompanies rapid, bulk edits in Node.js projects.