nodemon — CLI

What it is

nodemon watches files and restarts a wrapped command when something changes. Default-target is Node, but --exec makes it run anything. It's the long-time default dev-loop tool for Node servers. The native node --watch flag (Node 18.11+) covers the simple case, but nodemon's globs, debounce, config file, and event hooks are still worth the dependency.

For the package overview, see packages-npm/npm-nodemon. This page focuses on the CLI.

Install

npm install -D nodemon
# or
npm install -g nodemon

Output: nodemon binary in node_modules/.bin/ or on user $PATH.

Day-to-day commands

rs<Enter> in the terminal forces a manual restart.

Common scenarios

Watch a TS server

nodemon --watch src --ext ts,tsx,json --exec "tsx src/server.ts"

Output:

[nodemon] 3.1.0
[nodemon] watching path(s): src
[nodemon] watching extensions: ts,tsx,json
[nodemon] starting `tsx src/server.ts`
Server listening on :3000
[nodemon] file changed: src/api/users.ts
[nodemon] restarting due to changes...

Use nodemon.json to keep CLI short

{
  "watch": ["src", "config"],
  "ext": "ts,tsx,json,yaml",
  "ignore": ["src/**/*.test.ts"],
  "delay": "500ms",
  "exec": "tsx src/server.ts",
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  }
}

nodemon

Output:

[nodemon] config: nodemon.json
[nodemon] watching extensions: ts,tsx,json,yaml
[nodemon] starting `tsx src/server.ts`

Pass arguments through to the script

nodemon src/server.js -- --port 3001 --verbose

Output:

[nodemon] starting `node src/server.js --port 3001 --verbose`
server listening on http://localhost:3001

Everything after -- is forwarded to the wrapped process. Without --, nodemon swallows them as its own flags.

Lifecycle hooks (run shell commands on events)

{
  "exec": "node src/server.js",
  "events": {
    "start": "echo '🚀 starting'",
    "restart": "curl -s http://localhost:3000/health",
    "crash": "say 'Server crashed'"
  }
}

Useful for: warmup pings, desktop notifications on crash, Slack webhooks.

Debug mode

nodemon --exec "node --inspect-brk src/server.js"

Output:

[nodemon] starting `node --inspect-brk src/server.js`
Debugger listening on ws://127.0.0.1:9229/...

The --inspect-brk flag belongs to Node, not nodemon — pass via --exec. Then attach VS Code or Chrome DevTools.

Polling watcher for WSL / Docker / NFS

nodemon --legacy-watch --polling-interval 500 src/server.js

Output:

[nodemon] starting `node src/server.js`
[nodemon] using polling (500ms)

Native file events don't always propagate across virtual filesystems. Polling is slower but reliable.

Generic command-runner

# Re-build Go on .go changes
nodemon -e go --exec "go run ./cmd/server"

# Rebuild docker stack
nodemon --watch ./docker --ext yml --exec "docker compose up -d --build"

Output:

[nodemon] watching extensions: go
[nodemon] starting `go run ./cmd/server`

Useful flags

Configuration

nodemon.json (in project root) or nodemonConfig block in package.json:

{
  "name": "my-app",
  "scripts": {
    "dev": "nodemon"
  },
  "nodemonConfig": {
    "watch": ["src"],
    "ext": "ts,tsx,json",
    "exec": "tsx src/server.ts",
    "delay": "500ms",
    "env": {
      "NODE_ENV": "development"
    }
  }
}

Schema summary:

Common pitfalls

1. --inspect flag goes to nodemon, not Node. Use --exec "node --inspect src/server.js" instead.
2. WSL/Docker volumes miss changes. Switch to --legacy-watch.
3. Linux inotify watch limit exhausted. ENOSPC error — raise fs.inotify.max_user_watches or narrow the watch scope.
4. .gitignore is NOT honoured by default. Use explicit ignore patterns.
5. Editor atomic-write fires multiple events. Bump --delay to debounce.
6. Cannot find module after a restart. Probably restarted before npm install finished — wait then rs.
7. Restart on irrelevant file (e.g. .log). Tighten ext and ignore.

See also

• Packages: npm-nodemon — versioning, ecosystem
• JavaScript: node-runtime — native --watch alternative
• JavaScript: tsx — tsx watch for TS-only watch