Fine‑Tuning Nodemon: Mastering --watch and --ignore for Hot Reload

Problem: Too Many Restarts and High CPU Usage

When a Node.js project grows, the default Nodemon behaviour – watching only the entry script – often becomes insufficient. Developers frequently add new modules, move files into a src folder, or generate assets in a dist directory. Without explicit control, Nodemon will restart for every change, even in directories that don’t affect runtime, leading to noisy console output and wasted CPU cycles.

Why Watch & Ignore Matter

The --watch flag expands the set of watched paths beyond the default script file. Conversely, --ignore (or a .nodemonignore file) tells Nodemon to skip certain patterns. Together they give you a precise hot‑reload scope: only the files that truly matter trigger a restart.

Configuring Nodemon: Flags & Patterns

Below is a quick reference table for the most common flags used together:

Flag	Description	Example
--watch	Path(s) to watch for changes	--watch src
--ignore	Glob patterns to exclude from watching	--ignore node_modules
--delay	Milliseconds to wait before restarting after a change	--delay 0.5s
--exec	Command to run on restart (useful for adding flags to node)	--exec "node --trace-warnings"

Typical invocation for a project with a src directory and test files:

nodemon \
  --watch src \
  --watch lib \
  --ignore src/*.test.js \
  --ignore node_modules \
  --delay 0.5s \
  --exec "node --trace-warnings" \
  app.js

On Windows, remember to escape backslashes or use forward slashes in glob patterns, e.g., --ignore src\*.test.js becomes --ignore src/*.test.js in a .cmd script.

Practical Example

1. Install Nodemon globally: npm install -g nodemon. 2. Create app.js that logs a timestamp and exits on SIGINT. 3. Run the command shown above. 4. Edit src/index.js – the process restarts and logs the new timestamp. 5. Edit src/index.test.js – no restart occurs, confirming the ignore pattern. 6. Monitor CPU usage with top or htop to verify that only relevant directories consume resources.

Trade‑offs & Limitations

• Network or Virtual File Systems: On NFS or Docker volumes, Nodemon may fall back to polling, increasing CPU load.
• Too Many Watch Paths: Each added --watch path adds overhead. Keep the list focused.
• Deleted Files: If a watched file is removed, Nodemon may not trigger a restart. Handle SIGUSR2 or similar signals in your app if needed.
• Delay Parsing: In older Nodemon releases, passing a numeric value to --delay may be misinterpreted; always use a string with a unit (e.g., 1s).

Actionable Checklist

1. Identify the directories that contain code which should trigger a restart (e.g., src, lib).
2. List directories or file patterns that can be ignored (e.g., node_modules, dist, test files).
3. Add --watch and --ignore flags to your nodemon.json or CLI command.
4. Set an appropriate --delay to avoid race conditions in build pipelines.
5. Test the configuration by editing files in each category and observing restarts and CPU usage.
6. Document the setup in your project's README so new contributors can run the same dev environment.

Conclusion

By explicitly configuring --watch and --ignore, you turn Nodemon from a blunt restart tool into a fine‑tuned hot‑reload engine. It reduces noise, saves CPU, and gives you deterministic behaviour across diverse file systems.