DEV Community

R (RYUSLOG DEV)
R (RYUSLOG DEV)

Posted on Originally published at ryuslog.com

Next.js Standalone in Docker: Why Your CSS 404s and sharp Fails

You flip on output: "standalone" to shrink the Docker image, the container starts, the HTML arrives — and the page is completely unstyled. Every /_next/static/css/....css and /_next/static/chunks/....js request 404s, while next dev on your laptop looks perfect. Later, images start returning 500 with Error: Could not load the 'sharp' module using the linux-x64 runtime.

Two separate packaging bugs, one root cause: nobody told the image what standalone leaves out.

What output: "standalone" really emits

next build writes a self-contained server to .next/standalone: server.js, the traced node_modules your server code actually imports, and little else. It deliberately does not include .next/static (client CSS, JS chunks, fonts) and does not include public/. The Next.js team assumes a CDN serves those, so a Dockerfile that copies only .next/standalone ships a server whose every asset URL is a 404.

The layout mirrors the repository root, not your project directory — the single most common reason files "exist" in the image yet still 404:

.next/standalone/
├── server.js            # entry point: node server.js
├── node_modules/        # traced runtime deps only
└── .next/server/
.next/static/            # NOT included - must be copied
public/                  # NOT included - must be copied
Enter fullscreen mode Exit fullscreen mode

The Dockerfile that actually works

# 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 build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS run
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
# 1) traced server, 2) static assets, 3) public files
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
EXPOSE 3000
USER node
CMD ["node", "server.js"]
Enter fullscreen mode Exit fullscreen mode

Three details decide whether this works:

  • HOSTNAME=0.0.0.0. Without it the standalone server can bind to loopback, so the port mapping refuses connections while curl inside the container succeeds.
  • node server.js, not next start. The next CLI is not traced into the standalone tree; next start dies with sh: next: not found.
  • The destination path matters. .next/static must land at ./.next/static relative to the app root where server.js lives. Copying it to /app/static reproduces the exact 404s you started with.

The sharp module is a second, unrelated bug

sharp is an optional dependency with platform-specific native binaries. A node_modules tree installed on macOS, or under musl in an earlier stage, cannot resolve its binding in a glibc runtime stage.

Two commands settle the diagnosis:

docker run --rm my-app node -e "console.log(require('sharp').versions)"
docker run --rm my-app ls node_modules/@img
Enter fullscreen mode Exit fullscreen mode

No @img/* directory means the optional dependency was pruned — usually npm ci --omit=optional or a Yarn supportedArchitectures setting. If @img/sharp-linux-x64 exists but sharp.versions throws an ELF or GLIBC_2.28 not found error, the binary was built for a different libc.

Install in the same image and platform as the runtime, and keep sharp a regular dependency so tracing and npm ci agree:

FROM node:22-bookworm-slim AS run
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends libvips42 \
 && rm -rf /var/lib/apt/lists/*
RUN npm ci --omit=dev
Enter fullscreen mode Exit fullscreen mode

Building on Apple Silicon for linux/amd64 needs --platform on every stage — sharp picks glibc or musl at install time and never downloads the other later.

What goes where

Artefact In standalone? Destination Symptom when missing
server.js + traced deps Yes /app Container exits instantly
.next/static/** No /app/.next/static Unstyled HTML, 404 on assets
public/** No /app/public 404 favicon, og-image, robots.txt
.next/cache (ISR) No mount a volume Re-render on every request

To drop sharp from the critical path, images: { unoptimized: true } or an external loader removes the native dependency — at the cost of on-the-fly resizing and AVIF.

Edge cases before you debug blind

Assets present but still 404 behind a proxy. An nginx try_files or Traefik rule that routes only / to the app, or strips a prefix, breaks the /_next/* URLs the HTML references. Proxy the whole host, or set assetPrefix to point the HTML at a CDN.

ISR silently disappears. Standalone writes ISR pages to .next/cache inside the container; with a read-only root or several replicas each pod renders cold. Mount a tmpfs at /app/.next/cache.

Verify the deployment, not the log

Do not trust "the container started". Check status, content type and cache header from outside — the cURL builder generates the command in one paste, and the text diff tool compares emitted chunks between two builds before you blame the image.

The full write-up, with the reproducible layout, the monorepo tracing root variant and the ISR volume snippet, is on my site: Next.js Standalone in Docker: Missing CSS and sharp Module Errors.

Top comments (0)