Transforming Development with Docker Compose Watch

Let’s get something straight: building containers during dev is slow, repetitive, and wildly inefficient — especially if you’re rebuilding the entire image just because you changed a few lines in index.js.

Docker Compose Watch fixes that. And no, it’s not some beta half-baked feature — it’s actually useful.

You make a change, Docker reacts. Instantly. Your app syncs or rebuilds automatically. No more docker-compose up --build every time you rename a function.

Let me show you how it works — and why it’s probably the best thing to happen to local Docker dev since bind mounts.

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:

`sync`#

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

Copies host changes into the container on save
Doesn’t restart or rebuild the container
Perfect for JS/TS/React/Flask/Django/Express/etc.

This replaces bind mounts in a cleaner, more controlled way.

`rebuild`#

1
- action: rebuild
2
  path: package.json

Triggers a full image rebuild when the watched file changes
Same as doing docker compose up --build <svc> behind the scenes
Ideal for dependency files or compiled languages

Use both — rebuild on config changes, sync everything else.

How to Use Docker Compose Watch#

Here’s the full loop:

Add a x-develop.watch section to your compose.yaml
Start services with:
Terminal window
```
1
docker compose up --build --wait
```
Run:
Terminal window
```
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. Use Sync for Hot Reload, Rebuild for State Changes#

Example:

Sync: ./src, ./templates, .env
Rebuild: Dockerfile, package.json, requirements.txt

2. Ignore What Doesn’t Matter#

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

You don’t want every temp file triggering a sync.

3. Optimize Your Dockerfile#

Use multi-stage builds and cache properly:

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

If you copy too early, Docker invalidates your cache every time.

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.

SIGNAL & INTEL#

The Private Order: Stop being a grunt. Become an Architect. Join The Private Order.

_{DOCKER CAPTAIN · HASHICORP AMBASSADOR · AWS COMMUNITY BUILDER}