The Paradox of Thinner Images and Bulkier Builds

Moving a Next.js app to a multi-stage build and enabling standalone output shrinks image size by about 80%. But measure wall-clock time in the deploy pipeline and the build is often slower, not faster. Dependencies get re-downloaded every time, and caches keep getting invalidated. The image gets thinner while the time grows. This paradox comes from the surface of image optimization telling a different story than the substance.

Only the image got thinner, the build is still the same size

A multi-stage build splits into three stages. A stage that only installs dependencies, a stage that runs next build, and a runtime stage that only carries the output. The last stage just copies the standalone directory, .next/static, and public. No devDependencies, no full source. That's why the image is light. Images that used to exceed 1GB often drop to around 150MB. Just looking at that number, the optimization looks like a success.

The contradiction shows up in the next step. Standalone is produced by next build tracing the source and its dependencies. That means the build stage needs all the devDependencies—TypeScript, ESLint, tailwind—present. The image you deploy is thin, but the build that runs on every deploy is still heavy. You made the body lighter; you didn't make the engine smaller.

That heavy build keeps breaking the layer cache. Docker rebuilds every layer after the one that changed, no matter how small the change. That's why the convention is to copy package.json and the lockfile first, run npm ci, and copy the source afterwards. The intent is to keep the node_modules layer cached even when a single line of source changes.

This convention holds under one condition: the lockfile must not change often. In a repo where hand-run npm install makes the lockfile fluctuate, or dependency-update PRs land every day, the npm ci layer keeps breaking. Every time, all dependencies get re-downloaded. The image is thin, but a build that took 2 minutes now takes 10. The point is that cache viability rests on lockfile stability, not on layer ordering.

The more common mistake isn't ordering but the copy approach. Put npm ci after COPY . . and any source change invalidates the dependency layer. Without a .dockerignore, node_modules, .next, and .git get shipped into the build context in full and transferred to the daemon every time. No matter how well you set up the cache policy, that transfer cost remains. If the context is 300MB, every single-line source change shuttles 300MB back and forth. The file that fixes this isn't the Dockerfile—it's a single .dockerignore.

Decision memo: what to trim, what not to touch

Before starting optimization, here are three criteria worth writing down.

The runtime stage is genuinely safe to trim. Use standalone and don't copy node_modules wholesale. Splitting .next/standalone, .next/static, and public into separate COPY statements also buys you layer separation. There's one trap here. Standalone doesn't include static assets. Skip the .next/static copy and the image will throw 404s—and you'll only discover that at runtime, after a successful build. That's why a first deploy can go up cleanly with the static files entirely missing.

The build stage is a target for time, not size. This image isn't deployed anyway. The goal instead is to eliminate the dependency re-download on every build. BuildKit's cache mount does exactly that.

FROM node:20-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN --mount=type=cache,target=/root/.npm npm run build

Adding --mount=type=cache,target=/root/.npm keeps the tarball cache on the builder machine and avoids re-downloading without creating a new layer. npm ci still reconstructs node_modules, but it never hits the network. If your team uses private registry auth, you should also check that this cache doesn't hold auth tokens. Teams on pnpm can reach the same goal faster by pre-populating the global store with pnpm fetch.

The cache mount has blind spots too. If the CI runner is a fresh machine every time, the local cache dies with that build. Unless you set up buildx remote cache or registry cache, the mount cache is nearly useless in that environment. Where the cache survives depends on the environment. The right order is to check first whether you're on a local build, an always-on runner, or a runner that's spun up fresh each time.

Don't touch the ordering or the lockfile. Copy the package files first, keep the discipline of using npm ci, keep the lockfile stable. If any of these three breaks, expect the dependency layer to break about once a day. There's one more condition that's easy to miss. npm ci installs devDependencies too, unless NODE_ENV=production. It doesn't matter if you never rebuild node_modules in the runtime stage—but if npm is still present in the base image and someone accidentally runs npm ci again, image size quietly returns to where it started. No log, no error, no sign that a devDependencies layer just appeared.

Where the thinned image falls apart

Backfires usually come from something that wasn't an optimization target. Switching to Alpine to shave a few dozen more MB is the classic example. Native modules like sharp need musl binaries, not glibc. With no prebuilt binary available it falls back to compiling from source, and at that moment you need python3 and gcc. Even if compilation finished in the build stage, if the runtime stage's Node version differs from the build stage's, binary compatibility breaks. Saving 20MB and then failing two deploys is a cost you can't easily make back. That's why so many teams settle for node:20-bookworm-slim.

Pinning the Node version is on the same axis. If the build stage runs Node 20 and the runtime stage runs Node 18, the artifacts the standalone output carries can misbehave at runtime. Pull the base version for both stages into a single ARG and the mismatch itself disappears. Most deploys that violate Next.js's minimum Node version trace back to exactly this.

The third failure point is validating by image size alone. The SIZE column in docker image ls is storage, not deploy cost. The time to pull an image from the registry depends on compressed transfer size. Measuring transfer bytes with docker save | gzip -c | wc -c immediately reveals whether the size optimization was wasted effort. Use docker history for per-layer footprint and the CACHED marker in the build log for cache hits. If you haven't recorded wall-clock time before and after the optimization, ask yourself what the current work is even for.

One criterion to keep

Reading this optimization as a size-versus-time tradeoff will always leave you lost. Don't ask what you trimmed—ask which layer gets rebuilt every time. The criterion is one: when you change a single line in a source file, does the node_modules layer's cache break? If it does, tracing whether the cause is the lockfile, the COPY ordering, or context transfer is the starting point. The team that cut a 1GB image to 100MB did less for itself than the team that took dependency installation from 10 minutes per deploy to zero. On the next deploy, instead of opening the image size report, open the CACHED lines in the build log.

Comments

Loading comments.