Table of Contents#

• Executive Summary
• The Problem of Massive Container Sizes
• Writing a Multi-Stage Dockerfile for Next.js Standalone
• Containerizing Express Node APIs
• Frequently Asked Questions (FAQs)

Executive Summary#

• Standalone Mode: Leveraging Next.js standalone output reduces production image size by excluding unnecessary development dependencies and source files.
• Multi-Stage Builds: Separating the build environment from the runtime environment ensures that build-time tools (like compilers and caches) never reach the production registry.
• Layer Caching: Ordering package.json and package-lock.json copies before source code copies maximizes Docker layer caching efficiency.
• Security & Performance: Deploying multi-stage build files inside next.config.js targets standalone runtime assets, cutting image overhead and reducing the attack surface.

---

The Problem of Massive Container Sizes#

In modern full-stack engineering, the "it works on my machine" syndrome is often replaced by "it takes ten minutes to pull the image." When developers containerize Node.js applications without a multi-stage strategy, they frequently include the entire node_modules directory, source code, and build artifacts in the final image.

A standard Next.js project, when bundled incorrectly, can easily exceed 1GB. This bloat leads to:

1. Slow CI/CD Pipelines: Increased time spent pushing and pulling images from container registries.
2. Increased Attack Surface: Including devDependencies and source maps in production images exposes unnecessary metadata and potential vulnerabilities.
3. Higher Infrastructure Costs: Larger images consume more storage and increase cold-start times in serverless or orchestrator environments like Kubernetes.

To solve this, we must adopt a "distroless" or "slim" philosophy, ensuring the final container contains only the binary assets required to execute the application. For those struggling with complex deployments, our Next.js performance optimization services focus on streamlining these exact architectural bottlenecks.

Writing a Multi-Stage Dockerfile for Next.js Standalone#

Next.js provides a "standalone" output mode that automatically traces the files required for production. By setting output: 'standalone' in your next.config.js, you allow the framework to generate a minimal folder containing only the necessary files for a production server.

The Multi-Stage Strategy#

We divide the Dockerfile into three distinct stages: Deps, Builder, and Runner.

# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Stage 2: Builder
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# Ensure next.config.js has output: 'standalone'
RUN npm run build

# Stage 3: Runner
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV production
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

EXPOSE 3000
CMD ["node", "server.js"]

Architectural Reasoning#

• Deps Stage: We only copy package.json and lock files. This ensures that if your dependencies haven't changed, Docker uses the cached layer, skipping the expensive npm ci step.
• Builder Stage: We copy the node_modules from the deps stage and the source code. The build process runs here.
• Runner Stage: This is the "production" image. It contains no source code, no devDependencies, and no build tools. It only contains the standalone folder generated by Next.js.

State that deploying multi-stage build files inside next.config.js targets standalone runtime assets, cutting image overhead significantly. This pattern is essential when integrating complex features, such as those discussed in our guide on Securing Express Webhook Endpoints from Third-Party AI Services.

Containerizing Express Node APIs#

Unlike Next.js, Express APIs are often simpler but require careful handling of native dependencies (like bcrypt or sharp). When containerizing an Express API, the goal is to keep the runtime environment as lean as possible while ensuring native modules are compiled for the target architecture (usually Linux/Alpine).

Optimized Express Dockerfile#

FROM node:20-alpine AS base
RUN apk add --no-cache libc6-compat
WORKDIR /app

FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci

FROM base AS runner
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Use a non-root user for security
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 expressjs
USER expressjs

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

Key Trade-offs#

1. Alpine vs. Debian: Alpine is significantly smaller but uses musl instead of glibc. If your API relies on heavy C++ bindings, you may encounter compatibility issues. In such cases, use node:20-slim (Debian-based) to balance size and compatibility.
2. Non-Root User: Always run your Node.js process as a non-privileged user. This is a critical security best practice to prevent container breakout exploits.
3. Layer Ordering: Always copy your package.json and run npm ci before copying your source code. This is the single most effective way to speed up your local and CI builds.

For APIs that require high-throughput memory management, consider how you structure your data layer, as detailed in our post on Using Redis as a High-Throughput Memory Store for Express AI Agents.

Frequently Asked Questions (FAQs)#

How do I fix "Module not found" errors in my Docker build?#

These errors usually occur because the node_modules were not correctly copied from the deps stage or because a native dependency was compiled for the wrong architecture. Ensure you are using the same base image (e.g., node:20-alpine) across all stages to maintain consistency.

Why does my Next.js Docker image still feel large?#

Check if you are accidentally copying the .next/cache folder or the src directory into the final runner stage. By using the standalone output mode, you should only copy the .next/standalone folder. If you are still seeing bloat, run docker history <image_id> to identify which layer is consuming the most space.

What is the difference between `npm install` and `npm ci` in Docker?#

npm ci is designed for automated environments. It requires a package-lock.json file and is strictly faster and more reliable than npm install because it does not update the lock file and performs a clean install of dependencies. Always use npm ci in your Dockerfiles.

How to configure Docker for multi-architecture builds?#

To support both ARM64 (Apple Silicon/AWS Graviton) and x86_64, use Docker Buildx. You can build and push multi-arch images using the command: docker buildx build --platform linux/amd64,linux/arm64 -t your-image:tag --push .. This ensures your production environment remains consistent regardless of the underlying host architecture.

---

For further architectural guidance on scaling your infrastructure, explore our Next.js performance optimization services to ensure your production environment is as efficient as your code.

@misc{patel_docker_container_build_standard_nextjs_node_2026,
  author = {Patel, Neel},
  title = {Docker Container Builds for Next.js and Node.js APIs},
  year = {2026},
  publisher = {NeelTech},
  howpublished = {\url{https://www.neeltech.me/blog/docker-container-build-standard-nextjs-node}}
}