Multi-Stage Builds

Separate build and runtime stages so TypeScript compilers, test runners, and devDependencies never ship to production.

Recipe

Quick-reference recipe card - copy-paste ready.

# syntax=docker/dockerfile:1
 
FROM node:24-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
 
FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
 
FROM node:24-bookworm-slim AS prod
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]

When to reach for this: Every Node.js API image. Multi-stage is the default pattern for TypeScript services on Node 24.

Working Example

# syntax=docker/dockerfile:1
 
FROM node:24-bookworm-slim AS base
WORKDIR /app
 
# ---- dependencies (cached layer) ----
FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci
 
# ---- compile TypeScript ----
FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev
 
# ---- production runtime ----
FROM node:24-bookworm-slim AS prod
WORKDIR /app
ENV NODE_ENV=production
 
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
COPY --from=build /app/dist ./dist
 
RUN chown -R node:node /app
USER node
 
HEALTHCHECK CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
 
CMD ["node", "dist/main.js"]

{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "start": "node dist/main.js"
  }
}

What this demonstrates:

• deps stage caches npm ci when only source changes
• build stage compiles TypeScript with full devDependencies
• prod stage copies only dist/ and production node_modules
• USER node after chown for non-root runtime

Deep Dive

How It Works

• Each FROM starts a new stage; only COPY --from= artifacts cross stage boundaries
• Earlier stages are discarded from the final image except copied files
• Layer caching: put slow steps (npm ci) before fast-changing steps (COPY src)

Stage Naming Patterns

BuildKit Cache Mounts (Optional)

RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev

Speeds CI rebuilds when lockfile is unchanged. Requires BuildKit (DOCKER_BUILDKIT=1).

Monorepo Variant

FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
COPY packages/api/package.json packages/api/
COPY packages/shared/package.json packages/shared/
RUN npm ci
COPY . .
RUN npm run build -w packages/api
 
FROM node:24-bookworm-slim AS prod
WORKDIR /app
COPY --from=build /app/packages/api/dist ./dist
COPY --from=build /app/node_modules ./node_modules
USER node
CMD ["node", "dist/main.js"]

Copy only the workspace package you deploy. Do not copy the entire monorepo into the runtime stage.

Gotchas

• Single-stage npm ci then delete devDeps manually - easy to miss files. Fix: use a dedicated prod stage with npm ci --omit=dev.
• Copying entire /app from build stage - drags src/, tests, and caches into prod. Fix: COPY --from=build /app/dist ./dist only.
• Native modules built in wrong stage - bcrypt compiled on macOS, run on Linux. Fix: compile inside the Linux build stage.
• Forgetting package-lock.json in prod stage - npm ci fails or installs wrong versions. Fix: copy lockfile to every stage that runs npm ci.
• Running as root in final stage - security scanners flag it. Fix: chown + USER node - see Non-Root Containers.
• Huge build context - slow CI. Fix: .dockerignore - see Image Slimming.

Alternatives

FAQs

docker build --target build -t api:debug .
docker run -it --entrypoint sh api:debug

Related

• Docker Basics - first container
• Image Slimming - .dockerignore and layer diet
• Distroless & Alpine Trade-offs - minimal runtime bases
• Non-Root Containers - permissions in final stage
• Docker Best Practices - section checklist

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.