Docker Chokidar Hot Reload Fix

A one-line fix for the notorious hot reload problem in Docker containers when developing with Node.js tools (Vite, Webpack, Directus Extensions, etc.) on macOS and Windows.

The Problem

When you mount a local directory as a Docker volume:

volumes:
  - ./src:/app/src

File watching doesn’t work on macOS and Windows because:

• Docker uses virtualized filesystems (VirtioFS, gRPC FUSE)
• Native inotify events don’t propagate from host to container
• chokidar (used by Vite, Webpack, nodemon, etc.) never detects changes
• Result: You change code, nothing reloads

This affects:

• Vite dev server
• Webpack dev server
• Directus Extensions
• Next.js dev mode
• Any Node.js app with hot reload

The Solution

Enable polling mode for chokidar:

CHOKIDAR_USEPOLLING=true

Add to your .env or docker-compose.yml:

Option 1: .env file

CHOKIDAR_USEPOLLING=true

Option 2: docker-compose.yml

services:
  app:
    environment:
      - CHOKIDAR_USEPOLLING=true

Option 3: Dockerfile

ENV CHOKIDAR_USEPOLLING=true

Why This Works

Polling mode checks file modification times at intervals instead of relying on kernel events that don’t work across Docker’s filesystem bridge.

Example: Directus Extensions

services:
  directus:
    image: directus/directus:latest
    volumes:
      - ./extensions:/directus/extensions
    environment:
      - CHOKIDAR_USEPOLLING=true
      - EXTENSIONS_AUTO_RELOAD=true

Now your TypeScript extensions hot reload properly!

Example: Vite in Docker

services:
  frontend:
    build: .
    volumes:
      - ./src:/app/src
    environment:
      - CHOKIDAR_USEPOLLING=true
    ports:
      - '5173:5173'

Platform Notes

Performance Tip

If polling feels slow, you can tune the interval:

CHOKIDAR_USEPOLLING=true
CHOKIDAR_INTERVAL=100  # milliseconds (default: 100)

Lower = faster detection, higher CPU usage.

TL;DR

Problem: Hot reload doesn’t work in Docker on macOS/Windows
Cause: Native file events don’t cross Docker’s virtual filesystem
Fix: CHOKIDAR_USEPOLLING=true in environment