🏗️ Multi-stage Builds

The Single-Stage Problem

In the last lesson you built a clean, cached image. But look closely at a typical build for a TypeScript or React app and a problem appears: everything used to build the app is still sitting in the final image.

# Single-stage build — the final image carries all its build tooling
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm install          # installs devDependencies too: TypeScript, webpack, etc.
COPY . .
RUN npm run build        # compiles into /app/dist
EXPOSE 3000
CMD ["node", "dist/server.js"]

That image ships the full node:20 OS, every dev dependency, the TypeScript compiler, source maps, and your original source — none of which the running server needs. The result is often 800 MB to 1 GB when the app itself is a few megabytes.

Before this feature existed, teams worked around it with two separate Dockerfiles or fragile cleanup scripts. Multi-stage builds solve it inside one file.

The Multi-stage Idea

The analogy is a construction site. To build a house you need scaffolding, cranes, cement mixers, and crews. But when the house is done, you do not leave the cranes parked in the living room — you take them away and keep only the finished house.

A multi-stage build works the same way. One build stage has all the heavy tooling and produces artifacts. A separate runtime stage starts fresh from a slim base and copies in only those artifacts. When the build finishes, Docker discards the build stage entirely — it never becomes part of the shipped image.

The dashed handoff is the whole trick: only the compiled artifacts cross from the build stage into the runtime stage. The compilers and dev dependencies stay behind and are thrown away.

Syntax: FROM ... AS and COPY --from

Two pieces of syntax make multi-stage builds work:

• FROM <image> AS <name> — each FROM starts a new, independent stage; AS gives it a name you can reference.
• COPY --from=<name> <src> <dest> — copies files out of a named stage instead of the build context.

# ---- Stage 1: build (named "build") ----
FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci                 # all deps, including devDependencies
COPY . .
RUN npm run build          # produces /app/dist

# ---- Stage 2: runtime (the final image) ----
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev      # ONLY production deps
COPY --from=build /app/dist ./dist   # grab compiled output from stage 1
EXPOSE 3000
CMD ["node", "dist/server.js"]

The last FROM in the file defines the image you actually ship. Stage build did its job — compiling — and is discarded. The runtime image contains the Alpine OS, production dependencies, and your compiled dist, and nothing else.

A Real Node.js Example

Here is a complete, production-ready multi-stage Dockerfile for a TypeScript Express API. It combines everything: named stages, caching-friendly ordering, production-only runtime deps, and a non-root user.

# ================= Build stage =================
FROM node:20.11 AS build
WORKDIR /app

# Install ALL deps (TypeScript, types, etc.) reproducibly
COPY package*.json ./
RUN npm ci

# Compile TypeScript -> JavaScript in /app/dist
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

# ============ Production deps stage ============
# A separate slim install of ONLY runtime dependencies
FROM node:20.11-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

# ================ Runtime stage ================
FROM node:20.11-alpine
WORKDIR /app
ENV NODE_ENV=production

# Copy production node_modules from the deps stage
COPY --from=deps /app/node_modules ./node_modules
# Copy compiled JS from the build stage
COPY --from=build /app/dist ./dist
COPY package.json ./

# Run as the built-in non-root user
USER node

EXPOSE 3000
CMD ["node", "dist/index.js"]

$ docker build -t api:2.0 .
$ docker images api
REPOSITORY   TAG   SIZE
api          2.0   135MB    # single-stage equivalent was ~950MB

React Built, Nginx Served

Multi-stage builds shine brightest for front-end apps. A React build needs Node and hundreds of megabytes of tooling — but the output is just static HTML, CSS, and JavaScript. Those static files need only a web server. So: build with Node, serve with tiny Nginx.

# ---- Build the React app with Node ----
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build          # outputs static files to /app/build

# ---- Serve the static files with Nginx ----
FROM nginx:1.27-alpine
# Copy ONLY the built static assets — no Node, no node_modules
COPY --from=build /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Named Targets: Dev vs Prod

You can build any named stage directly with the --target flag. This lets one Dockerfile serve both a development image (with dev tooling and hot reload) and a lean production image.

# Shared base with dependencies
FROM node:20-alpine AS base
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Development target: keep dev deps, run the dev server
FROM base AS development
ENV NODE_ENV=development
COPY . .
CMD ["npm", "run", "dev"]

# Build target: compile production artifacts
FROM base AS build
COPY . .
RUN npm run build

# Production target: slim runtime with only the build output
FROM node:20-alpine AS production
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

# Build just the development image
docker build --target development -t myapp:dev .

# Build the production image (the default final stage)
docker build --target production -t myapp:prod .

Practice & Quiz

FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/server.js"]

FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:1.27-alpine
COPY --from=build /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Best Practices & Pitfalls

✅ Do

• Name stages meaningfully with AS (build, deps, test)
• Use a heavy base for building and a slim base (alpine/slim) for the runtime stage
• Copy only the artifacts you need with precise COPY --from paths
• Install production-only dependencies (npm ci --omit=dev) in the runtime stage
• Keep caching-friendly ordering inside each stage (manifests before source)

❌ Don't

• Copy an entire stage's /app when you only need dist
• Reinstall dev dependencies in the runtime stage
• Forget the USER instruction just because the file got longer
• Assume the build tools "carry over" — only COPY --from artifacts survive

Summary

📚 Additional Resources

• Docker Docs — Multi-stage builds
• Docker Docs — BuildKit
• Docker Docs — COPY --from reference

🚀 What's Next?

Multi-stage builds cut the biggest chunk of image bloat. The next lesson, Image optimization, takes it further: choosing between alpine, slim, and distroless bases, combining layers, pruning caches, and measuring exactly where every megabyte goes.