Transforming Development with Docker Compose Watch

What Is watch in Docker Compose?#

It’s a feature (currently in alpha) that lets Docker Compose monitor your local files and:

• 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.)

Basically, it’s file-watching with intent — not just blind syncing, but targeted, rule-driven updates.

Sync vs Rebuild: Know the Difference#

There are two actions you can use in your compose.yaml:

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#

Here’s the full loop:

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 lives in real time — like development should.

Real Example: Node.js App with Hot Reload#

Let’s 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 change App.jsx, save, refresh your 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/, watch it reload in real time.

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#

You can use watch with:

• 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 question is how you structure your watches.

Bonus: No More Bind Mount Weirdness#

Bind mounts are great… until they’re not:

• OS quirks
• Permissions pain
• Performance tanks on Windows

Sync rules give you precision. Rebuild triggers give you control.

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 workflows should be fast. Not “10 seconds to build a container” fast — save-and-see-results-immediately fast.

That’s what Docker Compose Watch gives you. It’s not production magic. It’s dev experience magic. And it works.

You just write code. Docker does the rest.