Docker Containerization with output: "standalone"
Next.js provides the output: "standalone" configuration option, which automatically traces and packages only the production dependencies needed by your application. This shrinks Docker container image sizes from over 1.5GB down to ~120MB, eliminating node_modules bloat and enabling secure, multi-stage, rootless Docker deployments on AWS ECS, Kubernetes, or GCP Cloud Run.
Learning Objectives
Configure output: "standalone" in next.config.js for self-hosted containerization.
Construct a secure, multi-stage Dockerfile (deps, builder, runner).
Copy static assets and public directories correctly into the standalone server tree.
Run the production container as a non-root user for enterprise security compliance.
Prerequisites & Background Knowledge
Why Interviewers Care
Crucial for enterprise roles where Next.js applications are self-hosted in Kubernetes or enterprise cloud clusters rather than Vercel.
The Challenge
How does output: "standalone" work in Next.js? Write a production-ready, multi-stage Dockerfile that minimizes image size and runs as an unprivileged user.
Code Architecture & Implementation
1# Stage 1: Dependencies cache2FROM node:20-alpine AS deps3RUN apk add --no-cache libc6-compat4WORKDIR /app5COPY package.json package-lock.json ./6RUN npm ci78# Stage 2: Build the Next.js application9FROM node:20-alpine AS builder10WORKDIR /app11COPY --from=deps /app/node_modules ./node_modules12COPY . .13# Disable Next.js telemetry during build14ENV NEXT_TELEMETRY_DISABLED=115RUN npm run build1617# Stage 3: Production Runner (Ultra-small standalone image)18FROM node:20-alpine AS runner19WORKDIR /app20ENV NODE_ENV=production21ENV NEXT_TELEMETRY_DISABLED=12223# Create unprivileged system user for security compliance24RUN addgroup --system --gid 1001 nodejs && \25 adduser --system --uid 1001 nextjs2627# Copy static assets and traced standalone server28COPY --from=builder /app/public ./public29COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./30COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static3132USER nextjs33EXPOSE 300034ENV PORT=300035ENV HOSTNAME="0.0.0.0"3637# Run the standalone Node server directly without npm!38CMD ["node", "server.js"]
Architectural Explanation
Standard npm install packages hundreds of devDependencies (TypeScript, ESLint, Tailwind compilers) that are useless at runtime. With output: "standalone", Next.js analyzes the AST of your built application and copies ONLY the exact files and node_modules packages actually executed at runtime into .next/standalone. The resulting server.js file can run standalone with a raw node server.js command, slashing memory footprint, deployment time, and security attack surface.
Common Mistakes & Anti-Patterns
Forgetting to copy `.next/static` into `.next/standalone/.next/static`, causing all CSS and client JavaScript bundles to return 404 in production.
Running containers as root user (`UID 0`), violating enterprise container security standards.
Copying the entire source `node_modules` directory into the final production image.
Interview Follow-Up Traps
The interviewer asks: "Why do client images break when I run the standalone Docker container?" Because static assets (`public/` and `.next/static/`) must be explicitly copied into the runner stage, or hosted separately on a CDN like S3/CloudFront.
Frequently Asked Questions
How do you configure health checks in the container?
Add a Docker `HEALTHCHECK CMD wget --spider http://localhost:3000/api/health || exit 1`.
Can standalone mode be deployed on Kubernetes?
Yes! It is the industry standard for deploying Next.js on AWS EKS, GCP GKE, and self-hosted Kubernetes.