🔥 Hot Reloading in Containers

The Instant-Feedback Loop

Hot reloading is the practice of automatically applying code changes to a running application without a manual stop-rebuild-start cycle. For a backend that usually means restarting the process; for a frontend it can mean Hot Module Replacement (HMR) — swapping a single module in the live page while keeping your scroll position and component state.

The payoff is real: instead of waiting seconds (or on a big app, tens of seconds) for a rebuild, you see your change almost immediately. Over a day of dozens or hundreds of edits, that compounds into a very different working experience.

How Reload Works in a Container

Hot reload inside Docker is really two independent problems stitched together:

1. Getting the changed file into the container. The bind mount from the previous lesson (./:/app) already does this — edits on your host appear instantly in the container's filesystem.
2. Getting the process to notice. A file watcher inside the container detects the change and triggers a restart (nodemon) or a module swap (Vite/webpack HMR).

Step 1 is solved. This whole lesson is really about step 2 — and about the ways step 2 quietly breaks in containers.

Remember the volume recipe that makes any of this possible — bind-mount the source, anonymous-volume the modules:

volumes:
  - ./:/app              # deliver source edits live
  - /app/node_modules    # keep the container's installed modules intact

Backend Reload with nodemon

nodemon wraps your Node process and restarts it whenever a watched file changes. It's the standard choice for Express and other Node backends. Install it as a dev dependency and run it as your dev command.

# Dockerfile.dev — backend
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci                 # nodemon is in devDependencies
COPY . .
EXPOSE 4000
CMD ["npm", "run", "dev"]

# package.json (scripts)
{
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js"
  }
}

For fine-grained control, add a nodemon.json. Watching only src/ and ignoring tests keeps restarts snappy:

// nodemon.json
{
  "watch": ["src"],
  "ext": "js,json",
  "ignore": ["src/**/*.test.js"],
  "delay": 300
}

api-1  | [nodemon] 3.1.0
api-1  | [nodemon] watching path(s): src/**/*
api-1  | [nodemon] starting `node src/index.js`
api-1  | Server on http://0.0.0.0:4000
api-1  | [nodemon] restarting due to changes...
api-1  | Server on http://0.0.0.0:4000

Frontend HMR with Vite

Frontends get something better than a restart: Hot Module Replacement swaps just the changed module into the live page, preserving state. Vite (the default for modern React/Vue projects) does this out of the box — but two container-specific settings are non-negotiable.

1. Bind the server to 0.0.0.0

By default a dev server listens on localhost — meaning inside the container only. Your browser on the host would get "connection refused." Binding to 0.0.0.0 makes it accept connections from outside the container so your published port actually works.

// package.json
{
  "scripts": {
    "dev": "vite --host 0.0.0.0"
  }
}

2. Let the HMR websocket connect back

HMR pushes updates over a websocket. In a container the client sometimes can't figure out the right address to connect back to, and you'll see HMR "connecting..." forever. Pin it in vite.config.js:

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    watch: {
      // Poll when native FS events don't cross the mount (see next section)
      usePolling: true,
      interval: 100,
    },
    hmr: {
      // The host/port the BROWSER uses to reach the HMR socket
      clientPort: 5173,
    },
  },
});

# compose.override.yaml (frontend service)
services:
  web:
    build:
      dockerfile: Dockerfile.dev
    ports:
      - "5173:5173"
    volumes:
      - ./:/app
      - /app/node_modules
    command: npm run dev

The Polling Fix

Here's the single most common Docker-dev frustration: your bind mount is correct, the file is updated inside the container, but the watcher never fires. The cause is almost always that native file-system events don't propagate across the virtualized mount on macOS and Windows (and occasionally on certain network filesystems).

The universal fix is to switch the watcher from native events to polling — periodically re-scanning files for changes. Many JS tools watch via the chokidar library, which reads an environment variable to force polling everywhere at once:

# compose.override.yaml
services:
  web:
    environment:
      - CHOKIDAR_USEPOLLING=true   # force chokidar-based watchers to poll
      - CHOKIDAR_INTERVAL=100      # optional: poll every 100ms

Per-tool equivalents, if you'd rather be explicit:

Full-Stack Hot Reload

Putting it together: a Vite frontend, an Express API with nodemon, and a database — all hot-reloading, all started with one command. The frontend swaps modules on change; the API restarts on change; the database just runs.

# compose.yaml (base)
services:
  web:
    build: ./web
    ports:
      - "5173:5173"
  api:
    build: ./api
    ports:
      - "4000:4000"
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

# compose.override.yaml (dev conveniences, auto-merged)
services:
  web:
    volumes:
      - ./web:/app
      - /app/node_modules
    environment:
      - CHOKIDAR_USEPOLLING=true
    command: npm run dev
  api:
    volumes:
      - ./api:/app
      - /app/node_modules
    command: npm run dev

Edit a React component and the browser updates in place. Edit a route handler and nodemon restarts the API in under a second. Neither touches the database, whose data persists in its volume.

Practice & Quiz

// package.json
{ "scripts": { "dev": "nodemon --legacy-watch src/index.js" } }

services:
  api:
    environment:
      - CHOKIDAR_USEPOLLING=true

Best Practices & Pitfalls

✅ Do

• Bind-mount source and anonymous-volume node_modules — the foundation reload builds on
• Bind dev servers to 0.0.0.0 so the host can reach them
• Enable polling only when native events fail, and narrow the watch scope
• Set hmr.clientPort to the published port when the HMR socket won't connect
• Ignore node_modules, dist, and test files in your watcher config

❌ Don't

• Leave polling on globally on native Linux — you don't need it and it wastes CPU
• Watch your entire tree with a tiny poll interval over thousands of files
• Forget to publish the dev server's port in Compose (ports:)
• Ship these dev settings to production — hot reload belongs only in the override
• Rely on native FS events across a macOS/Windows mount and hope they work

Summary

📚 Additional Resources

• Docker Docs — Bind mounts
• Vite — server.host, server.watch & HMR options
• nodemon — configuration & legacy-watch
• chokidar — the file-watching library behind most JS tools

🚀 What's Next?

Fast feedback is great until something breaks and the container swallows the error. Next up: Debugging Containerized Apps — reading logs with logs -f, dropping into a shell with exec, and attaching a real debugger through the Node inspector on --inspect=0.0.0.0:9229.