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 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"]