Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

React dev server in Docker does not reload when you save a file

ErrorPage does not refresh after saving a file in the editor

Short answer

File-change events often do not cross from your host into a container, so the dev server never notices the edit. Make the watcher poll, edit files from the same side as the container (WSL2), or let Docker Compose sync changes with develop.watch.

  • Applies to Node.js 22, Vite, Create React App 5, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Edit a file and watch what the container sees. If the dev server prints nothing, the watcher got no event.

    docker compose logs -f web
  2. 2Match what you see, then jump to its fix

    1. 1CRA dev server running in the container, no recompile line after a saveCreate React App watcher misses edits and needs pollingFix
    2. 2You edit with a Windows editor on a project stored on the Windows diskVite on WSL2 or Docker with a WSL2 backend does not see Windows editsFix
    3. 3The container shows the old version of the fileSource is copied in, not synced, so the container never gets new filesFix

What does the error look like?

  • Page does not refresh after saving a file in the editor
  • Changes appear only after docker compose restart or a rebuild

Cause 1 of 3

Create React App watcher misses edits and needs polling

1Check

The CRA docs list CHOKIDAR_USEPOLLING for virtual machines where npm start misses edits. A container with your code on a mount can be in that situation.

docker compose exec web env | grep CHOKIDAR

2Fix

Turn on polling for the service. Polling uses more CPU, so use it only in development.

# compose.yaml
services:
  web:
    environment:
      - CHOKIDAR_USEPOLLING=true

3Verify

Recreate the container, edit a file and see the recompile line in the log.

docker compose up -d --force-recreate web

Confirmed by create-react-app.dev

Did this fix it?

Cause 2 of 3

Vite on WSL2 or Docker with a WSL2 backend does not see Windows edits

1Check

The Vite docs say file watching does not work when a Windows application edits files under WSL2, and that this also applies to Docker with a WSL2 backend.

pwd   # run inside the container or WSL: is the project on /mnt/c ?

2Fix

Keep the project inside the WSL2 file system and edit it from there. If you cannot, switch on polling, which Vite warns costs high CPU.

// vite.config.js
export default {
  server: {
    watch: { usePolling: true },
  },
};

3Verify

Restart Vite and save a file; the browser updates.

docker compose restart web

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

Source is copied in, not synced, so the container never gets new files

1Check

Compare a file inside the container with the one on your disk.

docker compose exec web cat /app/src/App.jsx

2Fix

Use Compose watch with the sync action, which copies changed host files into the container and suits hot-reload frameworks. Rebuild when package.json changes.

services:
  web:
    build: .
    command: npm run dev
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

3Verify

Start with watch, edit a file under src and see it reload.

docker compose up --watch

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Decide once whether the project lives on the host with polling, or in WSL2, and keep that rule.
  • Exclude node_modules from any sync or watch path.
  • Use polling only in the dev compose file, never in production.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.