Next.js Static Export, Standalone Output, and Docker Deployment
Export has no server, standalone has a pruned one, and the default expects a full install. The three COPY lines that decide whether a container renders CSS.

Quick Summary
next build has three output modes that are often confused because they all change .next. The default produces a hybrid build for a Next.js server. output: "standalone" produces that same server plus a minimal node_modules subset so a container can run it without installing dependencies. output: "export" produces a folder of static files with no server at all, which removes ISR, Server Actions, middleware, dynamic route handlers, and image optimisation.
Choosing wrongly is expensive. An export cannot serve revalidate, so a site that relies on ISR must be standalone behind a Node process. A standalone image that omits .next/static and public loads HTML with no CSS — the second most common deployment failure after a missing HOSTNAME.
Docker is the usual target. A three-stage build (deps, builder, runner) with output: "standalone" yields an image around 150–250 MB that starts in under a second and needs only node server.js.
Basic Syntax & Core Signatures
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone", // or "export"
images: {
// required for "export": no server-side optimiser exists
unoptimized: true,
remotePatterns: [{ protocol: "https", hostname: "images.example.com" }],
},
trailingSlash: true, // static hosts map /about to /about/index.html
basePath: process.env.BASE_PATH || "",
};
export default nextConfig;# syntax=docker/dockerfile:1.7
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
FROM node:22-alpine AS builder
WORKDIR /app
COPY /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
COPY /app/public ./public
COPY /app/.next/standalone ./
COPY /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]# Static export: build output is the deployable artifact
next build # writes ./out
# serve it with any static host, and make sure the host rewrites unknown paths to 404.htmlserver.js inside the standalone folder reads PORT and HOSTNAME. Binding to the default localhost inside a container makes the port unreachable from outside the container, which looks like a crash loop in logs that show a successful start.
Key Comparison Table
| Feature | Default build | output: "standalone" | output: "export" |
|---|---|---|---|
| Needs a Node server | Yes | Yes (node server.js) | No |
node_modules required at runtime | Yes, full install | No, pruned subset | No |
ISR / revalidate | Yes | Yes | No |
| Server Actions | Yes | Yes | No |
Middleware / proxy.ts | Yes | Yes | No |
| Route handlers | All methods | All methods | GET only, build time |
next/image optimisation | Yes | Yes | No, unoptimized: true |
Dynamic routes without generateStaticParams | Yes | Yes | Build error |
| Cookies, headers, sessions | Yes | Yes | No |
| Deployment target | Node host | Container, VM, Node host | CDN, S3, GitHub Pages, Netlify |
| Typical image size | n/a | ~150–250 MB | n/a, static files only |
| Deploy target | Recommended output | Watch out for |
|---|---|---|
| Vercel | Default | Nothing; platform handles tracing |
| Docker on ECS or Cloud Run | standalone | Copy static and public; set HOSTNAME |
| Kubernetes | standalone | readOnlyRootFilesystem breaks .next/cache |
| S3 + CloudFront | export | No server features; trailingSlash |
| GitHub Pages | export | basePath for project pages, no rewrites |
| Nginx serving a Node app | standalone | Proxy headers, health check path |
Practical Edge Cases & Deep Dives
1. The image with no CSS
output: "standalone" copies traced server files, not .next/static or public — the docs say so, and it is still the most common bug. Without the copy, HTML returns 200 and the browser requests /_next/static/css/... which returns 404, so the page renders as unstyled HTML.
COPY /app/public ./public
COPY /app/.next/static ./.next/staticVerify after deploying rather than after building:
curl -s http://localhost:3000 | grep -o '/_next/static/[^"]*\.css' | head -1 | \
xargs -I{} curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000{}2. sharp and the image optimiser in a pruned image
The standalone trace normally includes sharp, but when the optimiser is installed as an optional dependency of a platform-specific build, the traced copy can miss the binary. The symptom is Error: 'sharp' is required to be installed in standalone mode on the first image request. Two fixes: install sharp in the runner stage (RUN npm i sharp), or set images.unoptimized: true and serve pre-sized images.
3. Files that tracing cannot see
outputFileTracingIncludes exists because file tracing follows import statements, not runtime string paths. A route that reads a template from templates/email.html or a dictionary from locales/*.json at runtime will 404 only in production.
const nextConfig: NextConfig = {
output: "standalone",
outputFileTracingIncludes: {
"/api/report": ["./templates/**/*", "./locales/**/*"],
},
};4. Build-time environment in Docker
NEXT_PUBLIC_* values are compiled into the client bundle during npm run build inside the builder stage. Setting them with docker run -e does nothing for the client. Pass them as build args, or keep the value server-side and read it per request.
docker build --build-arg NEXT_PUBLIC_SITE_URL=https://example.com -t app .Also clear the build cache when a public variable changes, or the cached layer keeps the old value.
5. Static export limits that appear as build errors
With output: "export", a dynamic route without generateStaticParams fails the build with "Page ... is missing param ... which is required with output: export". That is a feature: the error names every route that cannot be prerendered. Route handlers must be GET and must not read request data at runtime; a POST handler in an exported build is simply unreachable. Plan for an external form endpoint or a third-party service for anything that writes.
// app/blog/[slug]/page.tsx — required for export
export async function generateStaticParams() {
const posts = await fetch("https://cms.example.com/posts").then((r) => r.json());
return posts.map((p: { slug: string }) => ({ slug: p.slug }));
}
export const dynamicParams = false; // 404 for anything not prerendered6. Health checks, graceful shutdown, and .next/cache
A container orchestrator sends SIGTERM and expects the process to exit; server.js handles it, but in-flight ISR revalidation can be cut. Mount .next/cache as a writable volume if the image runs with a read-only root filesystem, otherwise every revalidation fails silently and pages stay stale. For the health check, use a real route (/api/health returning 200) rather than /, because a dynamic home page can be slow under cold start and the probe will restart a healthy container.
Finally, pin the base image. node:22-alpine moves under you between builds; node:22.11-alpine3.20 does not. A base-image change can alter the traced optional dependencies and turn a working image into one that fails on the first image request.
Common Runtime & Configuration Mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Page loads unstyled | .next/static not copied into the image | Add the COPY line, verify with curl |
| Container starts, port unreachable | HOSTNAME left as localhost | ENV HOSTNAME=0.0.0.0 |
'sharp' is required in standalone mode | Optional binary not traced | Install sharp in the runner stage |
| Runtime file read 404s in production only | File tracing missed a runtime path | outputFileTracingIncludes |
| Client uses the staging URL in production | NEXT_PUBLIC_* baked during build | Build args, or read the value on the server |
| Export build fails on a dynamic route | generateStaticParams missing | Add it, or set dynamicParams = false and accept 404s |
| POST endpoint returns 405 after export | Static export has no server | Move the write to an external API |
| ISR silently stops after a day | Read-only .next/cache | Mount a writable volume |
Try matching browser tools
All toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesNext.js Parallel Routes and Intercepting Routes: Slot Layouts and Modals
Named slots render several pages in one layout, and (.) interception makes a click open over the page while a direct link renders the full route. Why every slot needs default.tsx.
Next.js ISR: Route Revalidate, revalidateTag, and On-Demand Invalidation
Two clocks and one trigger: route revalidate seconds, fetch-level tags, and a webhook that calls revalidateTag. A timer is a ceiling on freshness, never a guarantee.
Next.js Environment Variables: NEXT_PUBLIC_, Build-Time Inlining, and Runtime Config
The prefix decides whether a value is compiled into the browser bundle or stays on the server. One image, two environments, and the choice that follows from it.
Next.js Link and Router: useRouter, usePathname, and useSearchParams
Client navigation goes through Link and the router hooks, the server uses redirect(). The Suspense requirement, prefetch cost, and query string handling that breaks first.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.