Nodemon Docker Mac: legacyWatch Fix for Stale Code

I watched a junior dev spend forty-five minutes debugging what turned out to be a change he'd made that was never actually running — because he'd forgotten to restart his server after saving the file. Not once. Three times in the same afternoon. That's not a character flaw; it's a workflow problem, and Nodemon exists to eliminate it entirely.

Node.js doesn't watch your files. When you start a Node.js server with 'node app.js', it loads your code once into memory and runs it. The moment you change a file and save it, Node.js has absolutely no idea. It's still running the old code. The only way to pick up your changes is to kill the process and restart it manually. In a fast feedback loop where you're editing, checking, editing, checking — that's a tax you pay hundreds of times a day. It sounds minor until you've done it for three hours straight and your muscle memory is shot and you've introduced a bug because you were staring at stale output.

After reading this, you'll be able to install Nodemon, wire it into any Node.js project, configure it to watch exactly the files you care about, ignore the ones you don't, and set it up so that every developer who clones your repo gets the same workflow automatically. You'll also know the three configuration mistakes that cause Nodemon to restart infinitely or miss changes entirely — both of which I've seen derail entire dev sessions.

Why Nodemon Needs a Docker Fix on Mac

Nodemon is a file-watching utility that restarts a Node.js process when source files change. Its core mechanic: it monitors the filesystem for modification events and kills/restarts the running process automatically. On Mac inside Docker, the default polling mechanism fails because macOS's native file events (fsevents) don't propagate reliably through Docker's filesystem layers. The result: nodemon misses changes, and developers manually restart containers — defeating the purpose. The fix is legacyWatch: true, which forces nodemon to use filesystem polling instead of event-driven watching. Polling checks file timestamps every interval (default 1 second), trading CPU overhead for correctness. In practice, this means nodemon works reliably in Docker-on-Mac environments, but you must configure it explicitly — the default behavior is broken. Teams that skip this setting waste hours debugging 'why didn't my code reload?'

Why Manual Restarts Kill Your Flow (And What Node.js Actually Does)

Before you can appreciate what Nodemon does, you need to understand why Node.js doesn't auto-restart by itself — and it's not an oversight, it's a deliberate design decision.

When you run 'node server.js', Node reads that file, compiles it to bytecode, loads it into memory, and starts executing. From that point on, Node is a running process. It owns a port, it holds database connections, it has state in memory. It doesn't scan your file system for changes because that's not its job. Its job is to serve requests as fast as possible. Polling the disk constantly would waste CPU cycles and slow everything down. So Node.js makes a deal with you: 'I'll be blazing fast, but you handle restarts.'

In development, that deal is terrible. You're changing files every two minutes. Every change requires a Ctrl+C and 'node server.js' again. Worse, you'll forget. You'll save a file, test your endpoint, get the old behaviour, spend ten minutes convinced your logic is wrong, and then finally notice you never restarted. I've seen this exact scenario cause someone to revert a perfectly correct fix because they thought it 'didn't work.'

Nodemon solves this by wrapping the Node.js process. It watches your project files for changes, and when it detects one, it kills the current Node.js process and starts a new one automatically. Your server is always running the latest version of your code. You save, you flip to Postman or your browser, your change is there.

// io.thecodeforge — JavaScript tutorial

// A minimal Express server — the kind you'd have at the very start
// of building a REST API for, say, a product catalogue service.
// Without Nodemon, every change to this file means manually restarting.

const express = require('express');

const app = express();
const PORT = 3000;

// Parse incoming JSON request bodies (needed for POST/PUT endpoints)
app.use(express.json());

// A simple health-check route — the first thing any real API should have.
// Load balancers and monitoring tools ping this to know the service is alive.
app.get('/health', (req, res) => {
  res.status(200).json({
    status: 'ok',
    timestamp: new Date().toISOString()
  });
});

// A placeholder products route — imagine this hitting a database next.
app.get('/products', (req, res) => {
  res.status(200).json({
    products: [
      { id: 1, name: 'Wireless Keyboard', price: 79.99 },
      { id: 2, name: 'USB-C Hub',        price: 49.99 }
    ]
  });
});

// Start the server and bind it to the port.
// Without Nodemon: change ANYTHING above, and this output is lying to you
// until you manually kill and restart the process.
app.listen(PORT, () => {
  console.log(`Product API running on http://localhost:${PORT}`);
  console.log('Tip: You are running the code that was loaded at START TIME.');
  console.log('Changes you make now will NOT appear until you restart.');
});

Installing Nodemon and Running Your First Auto-Restarting Server

Here's exactly how to get Nodemon running from nothing. Two decisions upfront: global install vs. local install. I'll tell you the right answer and explain why the other one causes problems on a team.

Global install means you run 'npm install -g nodemon' and the 'nodemon' command becomes available everywhere on your machine. Sounds convenient. The problem is that your teammates might have a different version, or a CI/CD pipeline won't have it at all. Six months later someone clones your repo, runs the start script, gets 'nodemon: command not found', and wastes half an hour figuring out why. Don't do global installs for project tooling.

Local install — 'npm install --save-dev nodemon' — puts Nodemon in your project's node_modules folder and records it in package.json under devDependencies. Anyone who clones the repo and runs 'npm install' gets the exact same version of Nodemon automatically. This is the only approach that works on a team or in CI. The '--save-dev' flag is critical: Nodemon is a development tool, not something that should ever run in production. Separating dev from production dependencies keeps your production Docker image lean and your deployment safe.

Once installed locally, you can't just type 'nodemon server.js' in the terminal — your shell doesn't know where to find it. You access it through npm scripts in package.json, which automatically add your local node_modules/.bin to the PATH when running scripts.

// io.thecodeforge — JavaScript tutorial

// This is your package.json — the configuration file at the root
// of every Node.js project. Think of it as your project's ID card
// and instruction manual combined.

// After running: npm install --save-dev nodemon
// Your package.json should look something like this:

{
  "name": "product-catalogue-api",
  "version": "1.0.0",
  "description": "REST API for product catalogue management",

  "scripts": {
    // 'start' is the production command — plain node, no Nodemon.
    // Never run Nodemon in production. It restarts on file changes,
    // which is the last thing you want on a live server.
    "start": "node server.js",

    // 'dev' is what every developer runs locally.
    // npm run dev => npm finds nodemon in node_modules/.bin automatically.
    // The --rs flag lets you manually type 'rs' + Enter in the terminal
    // to force a restart without changing any file (handy for env var changes).
    "dev": "nodemon server.js"
  },

  "dependencies": {
    // express belongs here — it runs in production
    "express": "^4.18.2"
  },

  "devDependencies": {
    // nodemon belongs HERE, not in dependencies.
    // --save-dev puts it here automatically.
    // This means 'npm install --production' skips it entirely.
    "nodemon": "^3.0.1"
  }
}

Configuring Nodemon: Watch the Right Files, Ignore the Rest

Out of the box, Nodemon watches all .js, .mjs, .cjs, and .json files in your project directory and restarts on any change. For a tiny project that's fine. For anything real, it'll drive you insane.

Here's the real problem: Nodemon doesn't know the difference between your source code and generated files, log files, or temporary files. If your app writes to a log file on every request — which is completely normal — and that log file is inside your project directory, Nodemon sees the write, thinks your code changed, and restarts. Which triggers another request. Which writes to the log. Which triggers another restart. I've seen this infinite restart loop on three separate teams. It eats CPU, it makes your logs unreadable, and it looks like the world's most confusing bug because the server is constantly restarting for no visible reason.

The fix is a nodemon.json configuration file. It sits at the root of your project alongside package.json and gives you precise control over what Nodemon watches, what it ignores, and what file extensions trigger a restart. Every serious Node.js project should have one. It makes the development experience consistent for every person on the team — nobody's getting phantom restarts because of local tooling differences.

// io.thecodeforge — JavaScript tutorial

// nodemon.json — place this at your project root.
// Nodemon reads this automatically when it starts. No flags needed.

{
  // 'watch' tells Nodemon exactly which directories to monitor.
  // Only changes inside these folders will trigger a restart.
  // Here we're only watching our source code folder, not the whole project.
  "watch": ["src", "config"],

  // 'ext' lists the file extensions that should trigger a restart.
  // We add 'env' because environment config changes need a restart.
  // We DON'T add 'log', 'tmp', or 'json' from generated folders.
  "ext": "js,json,env",

  // 'ignore' is your safety net — anything Nodemon should never restart for.
  // This is where you stop the infinite restart loop before it starts.
  "ignore": [
    "src/**/*.test.js",   // Don't restart when test files change — tests run separately
    "src/**/*.spec.js",   // Same for spec files
    "logs/*",             // Log files change on every request — NEVER watch these
    "node_modules/*",     // npm install changes these — never restart for this
    "coverage/*",         // Test coverage reports are generated, not source code
    "dist/*",             // Built/compiled output — not source code
    ".git/*"              // Git internals — definitely not source code
  ],

  // 'delay' adds a debounce in milliseconds before Nodemon restarts.
  // Without this, saving multiple files quickly (e.g. a refactor touching 5 files)
  // triggers 5 rapid restarts in a row instead of one clean restart.
  // 500ms is the sweet spot — long enough to batch saves, short enough to feel instant.
  "delay": 500,

  // 'env' injects environment variables specifically for the dev session.
  // This means you don't need a separate .env loader for local development basics.
  // For production, these come from your actual environment — NOT from here.
  "env": {
    "NODE_ENV": "development",
    "PORT": "3000"
  },

  // 'verbose' set to true prints exactly which file changed and why Nodemon restarted.
  // Turn this on when debugging a phantom restart — it'll name the culprit file immediately.
  "verbose": false
}

Nodemon With ES Modules, TypeScript, and Multi-Process Apps

Basic Nodemon for a CommonJS Express app is straightforward. But modern Node.js projects use ES Modules ('import'/'export' instead of 'require'), TypeScript, or even multiple processes. Each one needs a small adjustment or you'll hit a wall and not know why.

ES Modules in Node.js require either a .mjs extension or '"type": "module"' in your package.json. Nodemon itself handles this fine — the restart mechanism doesn't care about your module system. But the command you give Nodemon matters. If you're using '"type": "module"' and running Node 18+, plain 'nodemon server.js' still works. No change needed there.

TypeScript is the one that trips people up. Nodemon can't execute TypeScript directly — Node.js can't either. You need a TypeScript executor. The most common choice for development is 'ts-node'. You tell Nodemon to use ts-node as the executor instead of node, and it handles compilation on the fly. For larger projects, 'tsx' has become the faster alternative — it's built on esbuild and noticeably quicker for big codebases. I've seen teams on large TypeScript monorepos where ts-node's restart time was 8-12 seconds per change. Switching to tsx dropped that to under 2 seconds. That compounds over a full work day into real productivity.

For any of these setups, the exec key in nodemon.json is your control lever. It replaces 'node' with whatever executor you need.

// io.thecodeforge — JavaScript tutorial

// nodemon.json configured for a TypeScript Node.js project.
// This is the setup you'd use for a TypeScript Express API —
// the kind of thing you'd find in a fintech or SaaS backend.

{
  // 'watch' stays the same — source code directories only
  "watch": ["src", "config"],

  // Add 'ts' to the extension list — Nodemon now triggers on .ts file changes too
  "ext": "ts,js,json",

  "ignore": [
    "src/**/*.test.ts",
    "src/**/*.spec.ts",
    "dist/*",           // TypeScript compiles TO dist/ — never watch compiled output
    "node_modules/*",
    "logs/*"
  ],

  // 'exec' is the key that replaces 'node' with a different runtime/executor.
  // Here we use 'tsx' — dramatically faster than ts-node for large codebases.
  // Install it with: npm install --save-dev tsx
  // For ts-node instead: "exec": "ts-node src/server.ts"
  "exec": "tsx src/server.ts",

  "delay": 500,

  "env": {
    "NODE_ENV": "development",
    "PORT": "3000"
  }
}

// ─────────────────────────────────────────────────────────
// Your package.json scripts section with TypeScript:
// ─────────────────────────────────────────────────────────
// {
//   "scripts": {
//     "start": "node dist/server.js",        // Production: runs compiled JS
//     "build": "tsc",                         // Compile TS to JS for production
//     "dev":   "nodemon"                      // Dev: nodemon reads nodemon.json automatically
//   }
// }
//
// Note: 'nodemon' with no arguments reads nodemon.json and uses the 'exec' command.
// This is cleaner than putting everything in the npm script as flags.

Nodemon in Docker and Team Workflows

Running Nodemon inside a Docker container is common for development, but it introduces a critical gotcha: file change detection across volume mounts.

On Linux hosts running Docker natively, filesystem events (inotify) propagate correctly. Nodemon works out of the box. But on macOS (Docker Desktop) and Windows, the host filesystem is mounted via a network-like layer (osxfs on Mac, SMB on Windows). These layers do not forward inotify/FSEvents signals into the container. Nodemon sees nothing. You edit a file on your host, the container's filesystem updates, but Nodemon's watcher receives no event. You stare at a stale server.

The fix is polling mode. Set '"legacyWatch": true' in nodemon.json. This tells Nodemon's chokidar to poll the filesystem every few seconds instead of waiting for events. It uses more CPU (about 2-5% on a modern machine) but it's reliable across all Docker environments. Set the polling interval via '"pollingInterval": 1000' (milliseconds) to control frequency.

Another team workflow concern is consistent Nodemon configuration across multiple developers. The only way to guarantee this is to commit a nodemon.json file to your repository. Do not rely on each developer having the right global config or CLI flags. The nodemon.json file is checked in, versioned, and every team member sees exactly the same behaviour. If someone needs a local override (e.g., different port), they can use environment variables instead of modifying the committed config.

// io.thecodeforge — JavaScript tutorial

// nodemon.json for Docker development on macOS/Windows
// Enables polling mode to work around missing filesystem events

{
  "watch": ["src", "config"],
  "ext": "js,json,env",
  "ignore": [
    "src/**/*.test.js",
    "src/**/*.spec.js",
    "logs/*",
    "node_modules/*",
    "coverage/*",
    "dist/*",
    ".git/*"
  ],
  "delay": 500,

  // Enable polling mode for Docker volume mount compatibility
  "legacyWatch": true,

  // Poll every 1000ms (default is 1000 if not set)
  "pollingInterval": 1000,

  "env": {
    "NODE_ENV": "development",
    "PORT": "3000"
  },

  "verbose": false
}

// ─────────────────────────────────────────────────────────
// Dockerfile.development snippet (optional):
// ─────────────────────────────────────────────────────────
// FROM node:20-alpine
// WORKDIR /app
// COPY package*.json ./
// RUN npm install
// COPY . .
// # Run with polling mode already set in nodemon.json
// CMD ["npm", "run", "dev"]

The One Config Mistake That Kills CPU on Large Projects

Nodemon's default behavior is to watch every file in your project directory. On a small Express API, that's fine. On a monorepo with 10,000+ files in node_modules, generated build artifacts, and log files — it'll peg your CPU at 100% and your editor will lag.

The root cause isn't nodemon being greedy. It's that developers don't understand how file-watching works under the hood. Nodemon relies on fs.watch or chokidar, which recursively scans directories for changes. Every time a file is saved, nodemon registers a change event, restarts your app, and re-scans the entire watch tree. Multiply that by hundreds of files, and you've got a feedback loop that kills performance.

The fix is brutally simple: be explicit about what nodemon should watch. Use the --watch flag or the nodemon.json config file to narrow the scope to your source directory only. Never watch node_modules, dist, .git, or log directories. The rule: if you didn't write it, don't watch it. Your CPU will thank you.

// io.thecodeforge — javascript tutorial

// nodemon.json — production-grade watch configuration
{
  "watch": ["src/"],
  "ext": "js,mjs,cjs,json,ts",
  "ignore": ["node_modules", "dist", "coverage", "*.log", ".git"],
  "delay": "500ms",
  "legacyWatch": false,
  "quiet": false
}

// Terminal output when nodemon runs with this config:
// [nodemon] watching path(s): src/**/*
// [nodemon] watching extensions: js,mjs,cjs,json,ts
// [nodemon] starting `node src/index.js`
// [nodemon] clean exit - waiting for changes before restart

Debugging Nodemon With Breakpoints — The Clean Way

Developers love nodemon for the auto-restart. They hate it when they attach a debugger and restarting the app kills their breakpoints and drops the debug session. The standard approach — using node --inspect with nodemon — is fragile because nodemon restarts the process, which releases the debug port.

Here's the production pattern: use nodemon's --inspect flag or pass the Node.js inspect argument through nodemon's exec map. This tells nodemon to manage the debugger lifecycle. When your app restarts, nodemon re-attaches the debugger to the new process on the same port. No session drops. No manual re-connect.

Second, set a delay for restarts during debugging. The --delay flag with a value like 2000ms gives you a two-second window after saving a file before nodemon kills the process. That extra time lets your debugger catch the last state of the old process. Without it, you can lose the context of the bug you were chasing.

Finally, combine this with source maps for TypeScript or Babel projects. If nodemon isn't configured to use transpiled source maps, your debugger will show you compiled code — not the original TypeScript you wrote. That's a waste of time. Add "execMap": {"ts": "node --require ts-node/register --inspect=9229"} to your config.

// io.thecodeforge — javascript tutorial

// nodemon.json — debugger-friendly config
{
  "watch": ["src/"],
  "ext": "ts,js,json",
  "execMap": {
    "ts": "node --require ts-node/register --inspect=9229"
  },
  "delay": "2000ms",
  "signal": "SIGTERM"
}

// Terminal output when starting with debug flag:
// $ nodemon --inspect src/index.ts
//
// [nodemon] starting `node --inspect=9229 src/index.ts`
// Debugger listening on ws://127.0.0.1:9229/...
// [nodemon] restarting due to changes...
// [nodemon] starting `node --inspect=9229 src/index.ts`
// Debugger listening on ws://127.0.0.1:9229/...

Introduction

Developing Node.js applications often involves a tedious cycle: make a code change, stop the server, and restart it manually. Nodemon eliminates this friction by automatically monitoring your project files and restarting the Node process whenever a change is detected. It wraps your application in a file-watching layer that triggers graceful restarts—preserving your debugging state when combined with the right flags. This guide covers everything from local setup to team workflows, with a focus on why each configuration choice matters. By the end, you'll avoid the common pitfalls that waste CPU cycles and break Docker containers. Nodemon is not just a convenience tool; it's a reliability layer that keeps your feedback loop tight during development, letting you stay in flow state without breaking concentration on manual restarts.

Prerequisites

Before installing Nodemon, ensure you have Node.js version 14 or higher installed on your system. You can verify this by running node --version in your terminal. A basic understanding of the command line and package.json scripts is helpful. If you are using Docker or working with TypeScript, ES modules, or multi-process apps, you will need additional configuration—covered later. No prior Nodemon experience is required; this guide starts from scratch. For local development, you should also have a Node.js project initialized (npm init) and a working server file (e.g., server.js or index.js). If you already have a project, make sure your dependencies are installed. These prerequisites ensure that Nodemon can correctly hook into your application's lifecycle without interference from missing modules or incompatible runtime versions.

// io.thecodeforge — javascript tutorial
console.log('Node version:', process.version);
if (Number(process.version.slice(1).split('.')[0]) < 14) {
  console.error('Upgrade Node.js to v14+ for Nodemon compatibility');
} else {
  console.log('✅ Node version meets requirements');
}