Nodemon Tutorial: Automatically Restart Node.js Apps With Nodemon

Every Node.js developer knows the frustration of constantly stopping and restarting the server during development. Whether you're building APIs with Express, real-time applications with Socket.io, or microservices with Node.js, the traditional workflow of saving code, stopping the server with Ctrl+C, and restarting with node server.js breaks concentration and slows iteration.

Nodemon eliminates this friction by automatically watching your files and restarting your Node.js application whenever changes are detected. This essential development tool has become a standard in the Node.js ecosystem, used by developers worldwide to streamline their workflow and maintain focus on writing code rather than managing server processes.

In modern web development with Next.js and React, where hot reloading handles frontend changes automatically, backend development with Node.js benefits equally from similar automation. Nodemon serves as that automated restart mechanism, watching not just your main application files but also configuration files, database schemas, and any other resources your application depends on.

What Is Nodemon and Why You Need It

The Development Restart Problem

When building Node.js applications, each code change requires restarting the server to take effect. For a typical development session involving dozens or hundreds of code changes, this manual restart process adds significant friction to your workflow. You save your file, switch to the terminal, press Ctrl+C to stop the current process, press the up arrow to recall the start command, press Enter, wait for the server to initialize, then switch back to your editor. This cycle, repeated dozens of times per day, fragments your attention and interrupts the state of flow that effective programming requires.

Nodemon solves this problem by automating the restart process entirely. Once running, it monitors your project directory for file changes and automatically restarts your Node.js application when modifications are detected. The result is a seamless development experience where your changes are reflected immediately, allowing you to maintain focus on the task at hand.

How Nodemon Works Under the Hood

Nodemon operates by spawning your Node.js application as a child process and then monitoring the file system for changes. When a file modification is detected, Nodemon terminates the existing Node.js process and spawns a new one. This restart happens typically within a second or two, depending on your application's startup time. The tool uses file system events (inotify on Linux, FSEvents on macOS, and ReadDirectoryChangesW on Windows) for efficient change detection rather than polling, ensuring minimal resource consumption even in large projects.

Beyond basic file watching, Nodemon provides several sophisticated features that enhance the development experience. It can be configured to ignore specific files or directories, watch only certain file types, delay restarts to prevent excessive restarts during bulk edits, and integrate with your existing tooling through command-line flags and configuration files.

Installing Nodemon

Global Installation

The simplest way to get started with Nodemon is through global installation using npm or yarn:

npm install -g nodemon

After installation, verify Nodemon is available:

nodemon --version

Global installation makes the nodemon command available anywhere on your system, suitable for projects where you don't want to add Nodemon as a development dependency. With Nodemon installed globally, you can now run any Node.js application using nodemon instead of node, and the tool will automatically restart your application whenever files change.

Local Project Installation

For most projects, installing Nodemon as a development dependency is the preferred approach:

npm install --save-dev nodemon

Or with yarn:

yarn add --dev nodemon

This adds Nodemon to your package.json's devDependencies, ensuring it's available in CI/CD pipelines and team environments. When installed locally, run using npx:

npx nodemon server.js

The local installation approach provides better version control and reproducibility, as your project's dependencies are explicitly defined and can be locked to specific versions.

Installation Verification

Create a simple test file to confirm everything is functioning:

// test.js - Simple Express server for testing Nodemon
const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
 res.send('Testing Nodemon!');
});

app.listen(port, () => {
 console.log(`Server running at http://localhost:${port}`);
});

Run this file with Nodemon: nodemon test.js. You should see Nodemon's startup message indicating it's watching your files. Now modify the response message and save the file--Nodemon will automatically detect the change and restart the server.

Basic Usage and Commands

Starting Your Application

Using Nodemon is straightforward: replace node with nodemon when running your application:

nodemon server.js

Nodemon will immediately start watching files and display its status in the terminal. From this point forward, any JavaScript file changes in your project will trigger an automatic restart.

For applications that accept command-line arguments, pass them after your filename:

nodemon server.js --port 8080 --env production

Manual Restart Commands

When Nodemon is running in an interactive terminal, you can type rs (for "restart") and press Enter to trigger an immediate restart without any file changes. This is handy when debugging startup issues or when you've made changes outside the watched file patterns.

Exit and Shutdown

Stop Nodemon by pressing Ctrl+C in the terminal where it's running. Nodemon will terminate both itself and any child Node.js processes it has spawned, ensuring a clean shutdown. If Nodemon fails to shut down properly due to hanging processes, you can press Ctrl+C multiple times to force termination.

Configuration Files

Creating nodemon.json

For projects with specific watching requirements, Nodemon supports configuration through a nodemon.json file:

{
 "restartable": "rs",
 "ignore": [
 ".git",
 "node_modules/**/node_modules",
 "*.test.js",
 "coverage/**"
 ],
 "watch": [
 "src/",
 "config/",
 "*.js"
 ],
 "ext": "js,json",
 "delay": "2500"
}

This configuration tells Nodemon to watch the src/ and config/ directories, ignore git data and test files, wait 2.5 seconds after detecting changes before restarting, and only monitor JavaScript and JSON files.

Configuring Through package.json

Configure Nodemon within your package.json:

{
 "name": "my-app",
 "nodemonConfig": {
 "restartable": "rs",
 "ignore": ["node_modules", "coverage"],
 "watch": ["src", "config"],
 "env": {
 "NODE_ENV": "development"
 },
 "delay": 1000
 },
 "scripts": {
 "dev": "nodemon index.js",
 "start": "node index.js"
 }
}

Command-Line Options Override

Configuration file settings can be overridden through command-line flags:

nodemon --watch '*' server.js

The command-line flags always take precedence over configuration file settings, giving you flexibility for special cases while maintaining sensible defaults for everyday use.

Advanced Configuration Options

Watch Patterns and File Extensions

{
 "watch": [
 "src/", // Watch entire directory
 "config/*.json", // Watch specific files with glob
 "package.json", // Watch single file
 "!**/node_modules/**"
 ],
 "ext": "js,json,ts,mjs"
}

By default, Nodemon watches JavaScript and JSON files. You can customize the file extensions it monitors using the ext option. For TypeScript projects, adding .ts to the watched extensions ensures that changes to your source files trigger restarts.

Ignore Patterns

{
 "ignore": [
 "*.test.js",
 "*.spec.js",
 "coverage/",
 "dist/",
 ".git/",
 "node_modules/",
 "*.log"
 ]
}

Properly configuring ignored files prevents Nodemon from restarting when changes occur to files that don't affect your application's behavior. Nodemon automatically ignores the node_modules directory by default, but you can add additional ignores for build outputs, test files, and log directories.

Restart Delay

{
 "delay": 2500
}

The delay is specified in milliseconds, so 2500 represents a 2.5-second wait. This approach is especially useful when using tools that make multiple file writes in quick succession, such as some IDEs that create temporary files during save operations.

Environment Variables

{
 "env": {
 "NODE_ENV": "development",
 "PORT": 3000,
 "DEBUG": "app:*"
 }
}

These environment variables are applied when Nodemon spawns your application, ensuring consistent development settings regardless of terminal configuration.

Using Nodemon with Scripts

npm Script Integration

The most common and recommended approach for using Nodemon in modern Node.js projects is through npm scripts:

{
 "scripts": {
 "dev": "nodemon index.js",
 "dev:debug": "nodemon --inspect-brk index.js",
 "start": "node index.js"
 }
}

With these scripts defined, you can start your development server with npm run dev (or npm run dev:debug for debugging), and the command will use the locally installed version of Nodemon.

Multiple Entry Points

Some applications require running multiple Node.js processes, such as a main server and a background worker:

{
 "scripts": {
 "dev:server": "nodemon server.js",
 "dev:worker": "nodemon worker.js",
 "dev": "npm run dev:server & npm run dev:worker"
 }
}

This configuration allows you to run both processes concurrently using npm run dev. The & operator runs both processes in the background, allowing you to see output from both in the terminal.

Running Tests with Nodemon

While you typically don't want Nodemon watching test files during development, you can use it for scenarios where your application needs to remain running during testing:

{
 "scripts": {
 "dev:test": "nodemon --exec 'jest --runInBand' --watch 'src/**' --ignore '**/*.test.js'"
 }
}

This pattern is useful for test-driven development where you want your application to restart and re-run tests whenever source files change.

Docker Integration

Using Nodemon in Docker Containers

Running Nodemon inside Docker containers enables automatic restarts during local development even when your application is containerized. To use Nodemon in Docker, add it to your Dockerfile's development stage:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci
RUN npm install --save-dev nodemon

COPY . .

CMD ["nodemon", "src/index.js"]

Docker Compose Configuration

version: '3.8'

services:
 app:
 build: .
 volumes:
 - .:/app
 - /app/node_modules
 ports:
 - "3000:3000"
 command: nodemon src/index.js
 environment:
 - NODE_ENV: development

The volume mount .:/app maps your local source code into the container, while the /app/node_modules anonymous volume prevents the local node_modules from overwriting the container's node_modules directory.

Hot Reloading Considerations

For Docker environments where native file system events aren't properly propagated, use polling-based watching:

nodemon --legacy-watch src/index.js

The --legacy-watch flag (or -L) enables polling-based file watching, which is more resource-intensive but works reliably in containerized environments where native watching fails.

Troubleshooting Common Issues

Nodemon Not Detecting Changes

Use the --dump flag to output Nodemon's effective configuration:

nodemon --dump config/server.js

For Docker or virtualized environments where native file system events may not propagate correctly, try using the --legacy-watch or -L flag to enable polling-based watching.

Excessive Restarts

If Nodemon restarts too frequently, review your ignore patterns to ensure that build outputs, temporary files, and editor swap files aren't triggering unnecessary restarts:

{
 "ignore": [
 "*.swp",
 "*.swo",
 "*~",
 ".DS_Store",
 "dist/**",
 "build/**",
 "coverage/**"
 ]
}

Consider increasing the restart delay to batch multiple rapid changes into a single restart.

Permission Issues

On Linux systems, file watching requires sufficient permissions. Increase the maximum number of files being watched:

echo 999999 | sudo tee -a /proc/sys/fs/inotify/max_user_watches

Port Already in Use After Restart

Ensure your application properly handles shutdown signals:

process.on('SIGTERM', () => {
 server.close(() => {
 console.log('Server shut down gracefully');
 process.exit(0);
 });
});

This ensures that when Nodemon terminates your process, your server properly releases the port before the process exits. For more on building robust Node.js applications, explore our JavaScript error handling guide to learn proper exception management patterns.

Best Practices

Development-Only Usage

Nodemon is a development tool and should never be used in production. Ensure your production deployment scripts use node directly:

{
 "scripts": {
 "dev": "nodemon index.js",
 "start": "node index.js"
 }
}

Running npm run dev uses Nodemon for development, while npm start uses node directly for production deployments.

Version Control Configuration

Include your nodemon.json in version control to share configuration across your team, but exclude sensitive information. Since environment-specific settings can also be configured in nodemon.json, ensure that sensitive values are handled through environment variables.

Performance Optimization

For large projects, be specific about what Nodemon watches:

{
 "watch": ["src/", "config/", "lib/"],
 "ignore": ["node_modules", "dist", "*.test.js"]
}

Excluding build outputs, test files, and large dependency directories reduces the filesystem events Nodemon must process, resulting in faster restart times and lower resource consumption.

Combine with Other Tools

Nodemon integrates well with other development tools. For TypeScript projects, use Nodemon with ts-node:

nodemon --exec ts-node src/index.ts

This approach eliminates the compile-restart-run cycle entirely for TypeScript development, providing a streamlined development experience. Pair Nodemon with ESLint's --cache flag to avoid unnecessary linting during restarts.

Conclusion

Nodemon transforms the Node.js development experience by eliminating the manual restart cycle that interrupts your workflow and breaks concentration. Through its intelligent file watching, configurable restart behavior, and seamless integration with existing development tools, Nodemon allows developers to maintain focus on writing code rather than managing server processes.

Whether you're building simple APIs or complex microservices, installing Nodemon and integrating it into your development workflow is one of the highest-impact productivity improvements you can make. Start with simple installation, then explore configuration options as your needs evolve. Your future self will thank you for the hours of accumulated time saved by never having to manually restart a Node.js server again.

For teams looking to optimize their Node.js development workflow, Nodemon is an essential tool that integrates seamlessly with modern practices including containerized development, TypeScript compilation, and automated testing pipelines.

Sources

1. Refine.dev - How to Use Nodemon to Automatically Restart Node.js Applications
2. LogRocket - Nodemon Tutorial: Automatically Restart Node.js Apps with Nodemon
3. DigitalOcean - How To Restart Your Node.js Apps Automatically with Nodemon