Transforming Development with Docker Compose Watch

What Is watch in Docker Compose?#

It’s a feature, still in alpha, that points Docker Compose at your local files and lets it do two things:

• Sync them into running containers (great for JS, Python, anything with hot reload)
• Rebuild the container when certain files change (like package.json, requirements.txt, etc.)

So it’s file-watching with intent. Not dumb mirroring. Every update is targeted and rule-driven, which is the whole point.

Sync vs Rebuild: Know the Difference#

Two actions live in your compose.yaml. Here they are.

1
- action: sync
2
  path: ./web
3
  target: /src/web
4
  ignore:
5
    - node_modules/

1
- action: rebuild
2
  path: package.json

How to Use Docker Compose Watch#

The full loop is short:

1. Add a x-develop.watch section to your compose.yaml

2. Start services with:

   1
   docker compose up --build --wait
   

3. Run:

   1
   docker compose alpha watch
   

Now your app updates in real time. That’s how development should feel.

Real Example: Node.js App with Hot Reload#

Say your project looks like this:

1
myproject/
2
├── web/
3
│   ├── App.jsx
4
│   └── index.js
5
├── Dockerfile
6
├── compose.yaml
7
└── package.json

Your compose.yaml:

1
services:
2
  web:
3
    build: .
4
    command: npm start
5
    x-develop:
6
      watch:
7
        - action: sync
8
          path: ./web
9
          target: /src/web
10
          ignore:
11
            - node_modules/
12
        - action: rebuild
13
          path: package.json

Start the service:

1
docker compose up --build --wait
2
docker compose alpha watch

Now edit App.jsx, save, and refresh the browser. Done.

Test It Yourself: Run a Live Demo#

Clone the official demo:

1
git clone https://github.com/dockersamples/avatars.git
2
cd avatars
3
docker compose up -d
4
docker compose alpha watch

Then hit:

1
http://localhost:5735

Change something in src/ and watch it reload while you look at it.

Pro Tips#

1
ignore:
2
  - node_modules/
3
  - dist/
4
  - *.log

1
COPY package.json .
2
RUN npm ci
3
COPY . .

Not Just for Node.js#

watch works far beyond Node. A few examples:

• Python/Flask → sync .py, rebuild on requirements.txt
• Go → rebuild on .go, mount volume for go run
• Java/Spring → rebuild on .java or pom.xml
• Rust → rebuild on Cargo.toml, cache your target dir

It’s universal. The only real question is how you structure your watches.

Bonus: No More Bind Mount Weirdness#

Bind mounts are fine, right up until they aren’t. You hit OS quirks. You fight permissions. And on Windows, performance just falls off a cliff.

Sync rules hand you precision. Rebuild triggers hand you control. No quirks attached.

TL;DR#

• docker compose alpha watch = auto-sync + auto-rebuild
• Use sync for live reload workflows
• Use rebuild for dependency changes or compiled code
• Clean alternative to bind mounts
• Works with any language, any stack

Final Take#

Dev loops should be fast. Not “wait 10 seconds for a container” fast. Save-and-see-it-immediately fast.

That’s what Docker Compose Watch buys you. It’s not production magic. It’s dev-experience magic, and it holds up.

You write code. Docker handles the rest.