Use nodemon.json to Replace CLI Flags and Decide When Nodemon Beats Node’s Built‑in Watch

The Problem: A Flag‑Frenzy That Hides Your Watch Logic

When you run npx nodemon app.js --watch src --ignore logs/* --ext js,ts --delay 500, you can quickly lose track of what each flag does. Every new feature or team member adds another flag, and the command line becomes a maintenance nightmare. The real question is: how do you keep your watch configuration consistent across the project while still allowing local tweaks?

nodemon.json – The Centralized Configuration File

Starting with Nodemon 2.0, a nodemon.json file in the project root can hold the same settings that the CLI accepts. The file is a normal JSON object, and each property maps directly to a CLI flag:

• watch – an array of glob patterns or directories to monitor
• ignore – globs that should never trigger a restart
• ext – comma‑separated list of file extensions to watch (default js,json)
• exec – the command that Nodemon runs (useful for TypeScript or Babel builds)
• delay – milliseconds to wait after a change before restarting, useful for debounce

CLI flags still work, but they override the corresponding JSON values. This gives you a committed team default while allowing a developer to add --config local.json for personal overrides.

Example nodemon.json

{
  "watch": ["src", "config"],
  "ignore": ["logs/*", "coverage/*"],
  "ext": "js,ts", 
  "exec": "ts-node src/index.ts", 
  "delay": 300
}

Run it with:

npx nodemon

To inspect the effective configuration after merging defaults, CLI flags, and the JSON file, use npx nodemon --dump. It prints a JSON blob showing which values came from where.

When Nodemon is Overkill: Node’s Built‑in --watch

Node 18+ ships a --watch flag that restarts the process when watched files change. For a simple project that only needs to re‑run a single script, node --watch app.js can replace Nodemon entirely, eliminating an extra dependency.

However, Node’s watch lacks several niceties that Nodemon provides:

• Fine‑grained ignore rules (e.g., logs/*)
• Extension filtering beyond .js and .json
• Custom exec commands (run Babel, TypeScript, or other preprocessors)
• Debounce delay to avoid rapid restarts
• Event hooks and a programmatic API for advanced tooling

If your workflow requires any of these, Nodemon’s nodemon.json is the right place to keep them.

Trade‑offs & Limitations

• Performance: Nodemon watches files via fs.watch or chokidar, adding a small overhead. Node’s native watch is slightly lighter but offers less control.
• Compatibility: The behavior of --watch changes across Node releases. Verify against the Node version you ship with.
• Production Use: Nodemon is not a process manager. It lacks clustering, graceful shutdown policies, and log rotation. For production, use systemd, PM2, or similar.
• Restart Guarantees: Restarts kill in‑memory state. Ensure your app handles SIGTERM or uses a graceful shutdown middleware.

Actionable Takeaway

1. Create a nodemon.json in the root of your project and move all repeatable watch settings into it. 2. Keep the CLI minimal (npx nodemon or npm run dev) so teammates can run the same defaults. 3. If you only need to restart a single script and are on Node 18+, try node --watch app.js first. If you hit the limitations above, switch back to Nodemon and use the JSON file. 4. Periodically run npx nodemon --dump to audit which flags are active and prune unused overrides. 5. Remember: Nodemon is for local dev. In CI or production, use the appropriate process supervisor.

Diagram Labels

• nodemon.json
• CLI flags
• Node --watch
• Development workflow