nodemon local development watcher guide

Scope nodemon to local development, design ignore patterns to prevent restart loops, and use --exec only for debuggers or custom Node flags.

Problem and takeaway

Adding nodemon to a production container or CI pipeline seems convenient: the process restarts whenever a file changes. In practice, nodemon is a development file watcher, not a production process manager. It restarts on build artifacts and logs, exposes debugger ports, and provides no reboot survival, resource limits, or structured logging.

The useful decision is to keep nodemon in devDependencies, scope it to local development, use --exec only for interpreters or debuggers, and design ignore patterns so generated files cannot trigger restart loops.

Requirements

Restart the Node process when watched source files change.
Run the application under a custom Node interpreter or flags, such as the inspector or experimental modules.
Prevent restarts caused by logs, coverage output, build directories, or dependency installs.
Keep nodemon out of production images and startup commands.

Smallest suitable design

Install nodemon as a development dependency:

npm install --save-dev nodemon

Add a nodemon.json file at the project root. This centralizes ignore behavior so it is not lost in shell aliases or editor settings:

{
  "ignore": [
    "logs/",
    "*.md",
    "dist/",
    "coverage/",
    "node_modules/"
  ],
  "delay": 500
}

Use a package.json script that launches the application through nodemon with --exec. The double dash separates nodemon options from the application entry point:

"scripts": {
  "dev": "nodemon --exec node --inspect -- index.js"
}

Where to run: a terminal at the project root. Permissions: a regular user account is sufficient; no sudo is required. Placeholder: replace index.js with the application entry point. Expected check: the terminal prints a Node inspector listening message, and saving a watched source file triggers a restart with the inspector still attached. Risk: --inspect opens a debugger port, typically 9229, which should be bound to localhost or firewalled in shared environments.

Trust and data boundaries

Nodemon trusts the filesystem it watches. Any file under the watch directory that matches the include glob can trigger a restart, including files created by builds, tests, or package managers. Treat the watch root as a trust boundary: exclude generated output explicitly rather than assuming it is safe.

The --exec option runs the watched script under another interpreter, for example node --experimental-vm-modules or node -r dotenv/config. Nodemon itself does not parse .env files; environment variables are passed through to the child process from the shell. Secrets exported in the shell are visible to the nodemon child process.

Changes to nodemon.json are not picked up by an already running nodemon instance. Restart nodemon after editing the configuration.

Operational checks

Confirm the installed version: nodemon --version. Compare against release notes for --exec, --delay, and nodemon.json behavior before adopting in a pipeline. This note assumes current stable nodemon behavior; verify the installed release.
Start the watcher: npm run dev.
Verify the debugger: look for the inspector listening message in the terminal.
Test an ignore pattern: create logs/tmp.log, modify it, and confirm nodemon does not restart. Then modify index.js and confirm it does restart.
Test debounce: edit multiple files quickly and confirm a single restart after the configured delay rather than one restart per file.

Failure modes

Failure mode	Cause	Check or mitigation
Restart loop	Build artifacts, logs, or test output match the watch glob	Add output directories to `ignore` in `nodemon.json` and verify with a temporary file
Cascade restarts	Bulk edits or `npm install` write many files at once	Use `delay` to debounce restarts; exclude `node_modules/`
Debugger exposure	`node --inspect` binds to all interfaces by default	Bind to localhost or restrict network access in shared development environments
Silent config change	Editing `nodemon.json` does not affect the running instance	Restart nodemon after configuration edits
No production supervision	Nodemon does not survive reboots or enforce resource limits	Use a process manager or container orchestrator in production

Conditions that would change the design

If the team needs remote debugging, replace direct inspector exposure with a local port forward or tunnel; do not expose 0.0.0.0:9229.
If the application must restart automatically after a crash in production, use a process manager such as systemd or a container restart policy instead of nodemon.
If a monorepo watches many packages, narrow --watch to specific source directories and add package-specific ignore patterns.
If CI needs to rerun tests on file changes, consider the test runner's watch mode rather than nodemon wrapping the test command.

Rollback

Because this change adds a development dependency and a script, rollback is removing nodemon from devDependencies and deleting the dev script. No production state is changed by adding nodemon to a local-only script.

Limitations

Nodemon is not a process manager, supervisor, or production runtime. It does not provide structured logging, resource limits, or restart-after-reboot behavior. The --exec behavior and nodemon.json handling should be verified against the installed nodemon version before use in a shared pipeline; this note does not claim a specific tested version.

Practical result check: after starting npm run dev, save a source file and observe one restart. Save a file matching an ignore pattern and observe no restart. If either observation fails, revise ignore patterns or restart nodemon to load updated configuration.

Using nodemon safely as a local development watcher