Nodemon Configuration Guide: Safe Hot‑Reloading for Node.js

Problem

Developers need a way to see code changes instantly without stopping and restarting the Node process manually. In a typical development loop, a file edit triggers a new process, but if the restart logic is fragile, the application can enter a restart loop or fail to bind to a port, breaking the workflow.

Requirements & Trust Boundaries

Nodemon is intended solely for local development. It must watch files that affect the running code, ignore files that are regenerated automatically, and avoid interfering with production process management. The trust boundary is that nodemon does not supervise the process after it exits; it only restarts when a watched file changes.

Smallest Suitable Design

The minimal viable configuration lives in a nodemon.json file at the project root. It declares:

• watch: directories or patterns that contain source files.
• ignore: patterns that should never cause a restart, such as build output or logs.
• exec: the command that launches the Node process, optionally through an alternate interpreter.
• delay: a millisecond pause between restarts to avoid port‑binding races.
• signal: the POSIX signal sent to the previous process before restarting.

These five keys constitute the smallest design that addresses the core concerns of file watching, loop prevention, interpreter flexibility, and graceful shutdown.

Operational Checks

Before using nodemon in a team setting, verify the following:

1. Run npx nodemon --help in any project with nodemon installed to confirm that --exec, --watch, --ignore, and --signal appear in the help output.
2. Create a nodemon.json with an ignore entry for a log directory, write a line to a file inside that directory, and ensure the process does not restart.
3. Start an HTTP server under nodemon, edit a watched .js file, and confirm the terminal logs a restart and that the new process re‑binds to the same port after the old one exits.
4. Check the installed version with nodemon --version; major version changes may alter default watched extensions or the default signal.

Failure Modes & Conditions That Change the Design

Several practical issues can force a redesign of the configuration:

• Continuous restart loops: watching a directory with heavy write activity (e.g., dist/ or logs/) without an ignore rule will cause nodemon to restart on every write, halting development.
• Port‑binding errors (EADDRINUSE): the default restart delay of 100 ms may be insufficient if the previous process holds the port open; increasing delay or using --delay solves this.
• Signal mismatch: frameworks such as Express or NestJS expect SIGINT or SIGTERM for graceful shutdown; overriding the default with --signal prevents premature termination.
• Production deployment: nodemon is not a process manager; it will not restart a crashed application, handle zero‑downtime deployments, or supervise health checks. In production you must replace nodemon with a dedicated manager (e.g., PM2, systemd, Kubernetes).

Practical Example

Assume a TypeScript project with the following layout:

my‑app/
├─ src/
│  └─ index.ts
├─ logs/
│  └─ app.log
└─ nodemon.json

The nodemon.json file:

{
  "watch": ["src"],
  "ignore": ["logs/*", "node_modules/*"],
  "exec": "ts-node src/index.ts",
  "delay": 500,
  "signal": "SIGINT"
}

Running the command from the project root:

npx nodemon --config nodemon.json

What happens:

• Nodemon watches src/ for changes to .ts, .js, and .json files (the default extensions are extended automatically when exec uses ts-node.
• Writes to logs/app.log are ignored, so the process stays alive.
• When src/index.ts is edited, nodemon sends SIGINT to the existing ts-node process, waits 500 ms, then launches a fresh instance.
• The new process re‑binds to the port after the previous one has released it, avoiding EADDRINUSE errors.

Verification steps:

1. Start the server and note the process ID shown in the terminal.
2. Edit src/index.ts (e.g., change a console.log message).
3. Observe the terminal output: a “restart” line appears, the old process exits, and a new process starts listening on the same port.
4. Check that logs/app.log continues to receive writes without a restart event.

Conclusion

Nodemon’s strength lies in its simple, declarative configuration that cleanly separates the concerns of watching, ignoring, and executing. By centralising these settings in nodemon.json, teams gain a consistent development experience while avoiding common pitfalls such as restart loops, port conflicts, and signal mismatches. Remember that nodemon is a development‑only tool; for production you must adopt a dedicated process manager that can handle crashes, health checks, and zero‑downtime restarts. When the observed behavior deviates from expectations — continuous restarts, EADDRINUSE errors, or missing signal handling — adjust the ignore, delay, or signal fields, verify the version, and re‑run the diagnostic checks outlined above.