Multi-stage Docker builds for Next.js

14 days ago

2 min read

By Juliano Alves

Shipping Next.js in containers means balancing reproducible builds, small images, and fast deploys. Multi-stage Dockerfiles separate dependency install, build, and runtime so production images exclude devDependencies and build tools.

Enable standalone output#

// next.config.js
module.exports = { output: 'standalone' };

next build emits .next/standalone with a minimal server.js and traced node_modules subset—ideal for copying into the final stage.

Example Dockerfile (sketch)#

# syntax=docker/dockerfile:1
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

Cache mounts for npm#

With BuildKit:

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

Speeds CI rebuilds when lockfiles change infrequently.

Distroless vs Alpine#

Alpine is small but musl can surprise native addons. Distroless (gcr.io/distroless/nodejs20-debian12) improves security posture; pair with multi-stage copy of standalone output.

Summary#

Standalone + multi-stage + non-root user is the baseline for production Next containers. Tune cache mounts and base image for your team’s constraints—not every app needs the smallest possible image if build time dominates.