804 words
4 minutes

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#

- action: sync
path: ./web
target: /src/web
ignore:
- 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#

- action: rebuild
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:

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

  2. Start services with:

    Terminal window
    docker compose up --build --wait
  3. Run:

    Terminal window
    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:

myproject/
├── web/
│ ├── App.jsx
│ └── index.js
├── Dockerfile
├── compose.yaml
└── package.json

Your compose.yaml:

services:
web:
build: .
command: npm start
x-develop:
watch:
- action: sync
path: ./web
target: /src/web
ignore:
- node_modules/
- action: rebuild
path: package.json

Start the service:

Terminal window
docker compose up --build --wait
docker compose alpha watch

Now change App.jsx, save, refresh your browser. Done.


Test It Yourself: Run a Live Demo#

Clone the official demo:

Terminal window
git clone https://github.com/dockersamples/avatars.git
cd avatars
docker compose up -d
docker compose alpha watch

Then hit:

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#

ignore:
- node_modules/
- dist/
- *.log

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

3. Optimize Your Dockerfile#

Use multi-stage builds and cache properly:

COPY package.json .
RUN npm ci
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.


Social Channels#


Community of IT Experts#


Is this content AI-generated?

No. Every article on this blog is written by me personally, drawing on decades of hands-on IT experience and a genuine passion for technology.

I use AI tools exclusively to help polish grammar and ensure my technical guidance is as clear as possible. However, the core ideas, strategic insights, and step-by-step solutions are entirely my own, born from real-world work.

Because of this human-and-AI partnership, some detection tools might flag this content. You can be confident, though, that the expertise is authentic. My goal is to share road-tested knowledge you can trust.

Transforming Development with Docker Compose Watch
https://www.heyvaldemar.com/transforming-development-with-docker-compose-watch/
Author
Vladimir Mikhalev
Published at
2023-06-15
License
CC BY-NC-SA 4.0