nodemon — Auto-Restart Node.js Apps on File Changes

Introduction

nodemon is a development utility that monitors file changes in a Node.js project and automatically restarts the process. It replaces the manual stop-and-start cycle during development, saving time on every edit.

What nodemon Does

• Watches source files for modifications, additions, and deletions
• Restarts the Node.js process automatically when changes are detected
• Supports custom watch directories, extensions, and ignore patterns
• Works with TypeScript, CoffeeScript, and other transpiled languages
• Can execute non-Node scripts (Python, Ruby, Make) on file change

Architecture Overview

nodemon wraps the child process it manages and uses chokidar (or native FS watchers) to monitor the file system. When a file matching the configured extensions changes, nodemon sends a kill signal to the child, waits for it to exit, then spawns a fresh process with the same arguments. A configurable delay prevents rapid restarts during burst edits.

Self-Hosting & Configuration

• Install globally (npm i -g nodemon) or as a dev dependency
• Create nodemon.json in the project root for persistent configuration
• Set watch to specify directories and ext to list file extensions (e.g., js,ts,json)
• Use ignore to exclude directories like node_modules or dist
• Add a nodemon key in package.json as an alternative to a separate config file

Key Features

• Zero-config default that watches the current directory for .js, .mjs, .cjs, and .json changes
• Graceful shutdown support via configurable signals (SIGUSR2, SIGTERM)
• Delay option (--delay 2) to batch rapid file changes into a single restart
• Event hooks (restart, crash, exit) for custom scripting
• Works seamlessly as a drop-in replacement for the node command

Comparison with Similar Tools

• ts-node-dev — focused on TypeScript with incremental compilation; nodemon is language-agnostic
• tsx watch — uses esbuild for fast TypeScript reloading; nodemon is broader but needs a separate transpiler
• entr — generic Unix file watcher; nodemon integrates tighter with Node.js process lifecycle
• watchexec — Rust-based file watcher; nodemon offers Node-specific features like graceful restart signals
• PM2 watch — PM2 includes a watch mode, but nodemon is lighter for pure development use

FAQ

Q: Can nodemon run TypeScript files directly? A: Yes. Use nodemon --exec ts-node server.ts or configure the execMap in nodemon.json to map .ts files to ts-node.

Q: How do I prevent nodemon from restarting on generated files? A: Add the directory or pattern to the ignore list in nodemon.json, for example ["dist", "*.test.js"].

Q: Does nodemon work inside Docker? A: Yes. Use --legacy-watch (or CHOKIDAR_USEPOLLING=1) if the container filesystem does not support native inotify events.

Q: Can I use nodemon in production? A: It is not recommended. Use PM2 or a proper process manager for production. nodemon is designed for development workflows.

Sources

• https://github.com/remy/nodemon
• https://nodemon.io/