Designing a Safe Nodemon Configuration for Development‑Only Restarts

Requirements

Development teams need a file‑watcher that restarts the application only when source code changes, ignores build artefacts, and prevents restart storms when editors or bundlers write many files at once. The watcher must stay out of production images and must not be granted elevated privileges.

Smallest Suitable Design

A single nodemon.json at the repository root is enough to express the required behaviour. The configuration declares:

• watch – directories that contain source files (e.g. src/, lib/).
• ignore – glob patterns for generated output (dist/**, build/**, coverage/**, logs/**, node_modules/**).
• ext – file extensions that should trigger a restart (e.g. js,ts,json).
• delay – debounce interval in milliseconds (default ~1000 ms) to coalesce rapid writes.
• exec – the command that starts the app (e.g. node src/index.js or ts-node src/index.ts).

{
  "watch": ["src", "lib"],
  "ignore": ["dist/**", "build/**", "coverage/**", "logs/**", "node_modules/**"],
  "ext": "js,ts,json",
  "delay": 1200,
  "exec": "node src/index.js"
}

Place this file in the project root and run npx nodemon (or nodemon --config nodemon.json) from the same directory. The command inherits the invoking user’s privileges; no sandboxing is provided.

Trust and Data Boundaries

Nodemon executes the target process with the same credentials as the developer’s shell. It does not validate the watched files, nor does it isolate the child process. Therefore:

• Only run nodemon on trusted codebases.
• Never add nodemon to dependencies or to a production Dockerfile CMD/ENTRYPOINT.
• Declare it under devDependencies in package.json.

Operational Checks

1. Verify ignore patterns – edit a file under dist/ (e.g. dist/bundle.js) and confirm no restart occurs. Then edit src/app.ts and confirm a single restart after the configured delay.
2. Confirm debounce – run a script that touches several source files within 200 ms (e.g. for f in src/*.ts; do echo "// change" >> $f; done). Observe that nodemon restarts once, not once per file.
3. Inspect production artefacts – run grep -r nodemon package.json Dockerfile docker-compose.yml and ensure the only matches are in devDependencies or development scripts.

Failure Modes

Symptom	Likely Cause	Mitigation
Repeated restarts on every save	Ignore patterns missing node_modules/** or build output directories	Add explicit globs to ignore; increase delay if needed.
No restart when source changes	Watch list does not include the edited directory or ext omits the file extension	Extend watch or ext accordingly.
EMFILE / ENOSPC errors from inotify	Too many watched directories (often node_modules not ignored)	Ensure node_modules/** is ignored; raise fs.inotify.max_user_watches on Linux if necessary.
Unexpected config precedence	Both nodemon.json and package.json#nodemonConfig present	Keep a single source of truth; remove the duplicate.

When to Re‑evaluate the Design

• Project migrates to a language/runtime that provides its own hot‑reload (e.g. vite, next dev).
• Team adopts a process manager for production‑like staging (PM2, systemd) and wants zero‑downtime reloads – nodemon cannot provide that.
• File‑watcher limits become a bottleneck even after ignoring node_modules; consider chokidar‑based alternatives or native FS events.
• Security policy requires sandboxed development tools – nodemon offers no isolation.

Practical Verification Checklist

• Create nodemon.json with the minimal config above.
• Run npx nodemon in the project root (no sudo required).
• Edit a watched source file → expect a single restart after ~1.2 s.
• Edit an ignored file (e.g. dist/main.js) → expect no restart.
• Run npm ls nodemon and confirm it appears only under devDependencies.
• Search deployment manifests for nodemon → none should be found.

Note: The behaviour described matches the current nodemon 3.x series. Because the research flag requiresCurrentVerification is true, treat the delay default, event names, and config‑merge precedence as items to verify against the locally installed version before locking the configuration in CI.