This content originally appeared on DEV Community and was authored by Darshan Vasani

What is a Multi-Stage Build in Docker?

Multi-stage build allows you to use multiple FROM statements in a single Dockerfile to:

• Build the app in one stage
• Copy only what’s needed to a smaller final image

Why Do We Need It?

Main Goals:

Benefit	Why it Matters
Smaller Images	Only copy what’s needed into final image
More Secure	No dev tools or secrets in production image
Cleaner CI/CD	Separate build & runtime environment
Better Layer Caching	Speeds up builds
Environment Separation	One image builds everything!

Real-World Analogy

Imagine:

• Stage 1 = Construction site (messy, heavy tools)
• Stage 2 = Finished house (clean, cozy)

You build in the messy environment, but only move the furniture into the clean house.

Multi-Stage Build Syntax

# 🔨 Stage 1: Build Stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 📦 Stage 2: Final Production Image
FROM node:20-alpine
WORKDIR /app

# Copy only final build artifacts (no source or node_modules)
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./
RUN npm ci --omit=dev

# Set env vars, port and run
ENV PORT=3000
EXPOSE 3000
CMD ["node", "dist/index.js"]

Key Concepts Explained

Before vs After: Image Size

Approach	Image Size	Contents
Traditional Single Build	~900MB	Full source code + dev dependencies
Multi-Stage Build	~200MB	Just built app + runtime dependencies

Real Project Example: React App

# Step 1: Build React App
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Step 2: Serve using NGINX
FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

This builds the app with Node.js, and serves the static files via NGINX (no Node.js in final image!)

Common Multi-Stage Use Cases

Use Case	Description
Frontend builds	Use node + nginx combo
Backend builds	Build with TS/Go/Rust, then copy binaries only
Testing stage	Add test/linting in one stage, skip in final
CI/CD pipelines	Clean, reproducible builds across stages

Pro Tips & Best Practices

Tip	Recommendation
Use --omit=dev	Strip dev-only packages in final stage
Use .dockerignore	Exclude node_modules, .git, tests/, etc
Use labels	Add metadata like version, author, etc
Don’t copy everything	Use exact COPY paths for size control
Use named stages	Easier to copy from (--from=builder)
Keep final image minimal	Just enough to run your app (no tools!)

Combine with Docker Compose

You can define multi-stage builds in your Dockerfile and just run:

docker-compose build
docker-compose up

Your services will use the optimized final image automatically

Example Multi-Stage for TypeScript API

# Stage 1: Compile TS
FROM node:20-alpine AS builder
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

# Stage 2: Run with only JS output
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --omit=dev
CMD ["node", "dist/server.js"]

Summary: When to Use Multi-Stage Builds?

Always use if:

• You’re using build tools like tsc, webpack, vite
• You want minimal production images
• You want to separate testing/staging/building
• You want faster CI builds & smaller attack surface

Final TL;DR Cheatsheet

Full Dockerfile (Context Recap)

FROM node:20-alpine3.19 as base

# Stage 1: Build Stuff
FROM base as builder

WORKDIR /home/build

COPY package*.json .
COPY tsconfig.json .

RUN npm install

COPY src/ src/

RUN npm run build

# Stage 2: Runner
FROM base as runner

WORKDIR /home/app

COPY --from=builder /home/build/dist dist/
COPY --from=builder /home/build/package*.json .

RUN npm install --omit=dev

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nodejs

USER nodejs

EXPOSE 8000
ENV PORT=8000

CMD [ "npm", "start" ]

A2Z Breakdown of Each Section

FROM node:20-alpine3.19 as base

What it does:

• Starts from a minimal Node.js 20 Alpine image
• Alpine is lightweight (~5MB), good for small, fast images
• as base names this stage for reuse

Think of base like a shared template that both stages use.

Stage 1: Builder

FROM base as builder
WORKDIR /home/build

What happens here:

• We switch to a new build stage, using base image
• WORKDIR /home/build sets a directory for our build process

COPY package*.json .
COPY tsconfig.json .
RUN npm install

Install dependencies:

• package*.json copied to install dependencies
• tsconfig.json is required for TypeScript compilation
• npm install installs all dependencies (dev + prod)

COPY src/ src/
RUN npm run build

Build your app:

• Copies your app’s TypeScript code
• npm run build compiles TS into JS → typically inside /dist

End Result of Stage 1:

A folder /home/build/dist with compiled production-ready JS output.

Stage 2: Runner

FROM base as runner
WORKDIR /home/app

What it does:

• We now create a fresh container just for running the app.
• WORKDIR /home/app is where your app will run from.

COPY --from=builder /home/build/dist dist/
COPY --from=builder /home/build/package*.json .

Copy built artifacts only:

• Only copy the dist/ folder and package files (no source, no tsconfig)
• Ensures the final image is slim & clean

RUN npm install --omit=dev

Production-only install:

• Installs only prod dependencies (no dev tools like eslint, tsc, etc.)
• Keeps final image light and secure

Add Secure Non-Root User

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nodejs
USER nodejs

Why?

• Running as root is dangerous in containers
• We create a user nodejs with limited permissions for safety
• UID/GID 1001 is just an arbitrary non-root system user

Port & Env Setup

EXPOSE 8000
ENV PORT=8000

• EXPOSE 8000: Documents that the app uses port 8000
• ENV PORT=8000: Sets the default port for app to use internally

You still need to use -p to map it to host:
docker run -p 8000:8000 <image>

Start the App

CMD [ "npm", "start" ]

Default entrypoint when container runs

• This triggers your "start" script from package.json:

  "start": "node dist/index.js"

Summary Table

Section	Purpose
FROM base	Reuse image to reduce duplication
builder	Compiles TypeScript into JS
runner	Runs a minimal production image
npm install in builder	Installs full deps for building
npm install --omit=dev in runner	Installs only what’s needed to run
COPY --from=builder	Efficient file copy without rebuild
USER nodejs	Enhances container security

Resulting Benefits

Benefit	Achieved
Small Image	Only runtime code in final image
Secure	Non-root user, no dev tools
Faster Builds	Reuses build layers
Clean Code Separation	No TypeScript or build files inside final container
Portable	Can run on any platform with Node 20

Bonus Tip: View Image Sizes

docker images

Compare the multi-stage image (~100MB) vs a single-stage image (~400–600MB)

Final Thoughts

This approach follows Docker best practices:

• Multi-stage
• Production-ready
• Secure by default
• Reproducible builds

This content originally appeared on DEV Community and was authored by Darshan Vasani