12.2.2.3 Node Hot Reload

Node hot reload within a containerized development setup combines a bind-mounted source directory with a file-watching development tool, automatically restarting or reloading the Node.js application whenever a source file changes, providing the fast, iterative feedback loop expected during active development.

Configuring Hot Reload for a Containerized Node.js Application

A development-specific command, typically using a tool like nodemon, watches for file changes within the bind-mounted source directory.

services:
  app:
    build: .
    volumes:
      - .:/app
      - /app/node_modules
    command: npx nodemon server.js

The second volume entry specifically excludes node_modules from the broader bind mount, preventing the host's potentially incompatible dependency installation from overwriting the container's own.

Why nodemon Specifically Suits This Containerized Pattern

nodemon watches the filesystem for changes and automatically restarts the Node.js process, working naturally with the bind-mounted source files made visible inside the container.

{
  "scripts": {
    "dev": "nodemon server.js"
  }
}

command: npm run dev

Addressing File-Watching Reliability on Non-Linux Hosts

On Docker Desktop for Mac or Windows, filesystem change events across a bind mount can sometimes be less reliable, occasionally requiring a fallback to polling-based detection.

nodemon --legacy-watch server.js

This polling-based approach trades some efficiency for more reliable change detection in these specific environments.

Verifying Hot Reload Is Actually Working

Making a small change and observing the container's logs confirms the development server correctly detects and reacts to it.

echo "// test change" >> server.js
docker compose logs -f app

Why Node Hot Reload Matters

Properly configured hot reload, built on a correctly excluded dependency mount and a reliable file-watching tool, is essential for a genuinely productive Node.js development experience within a containerized environment, removing the friction of manual restarts after every code change.