Standalone output for Docker: what developers should know

Deploying a Next.js application to production often means wrestling with Docker image size. A standard Next.js build bundled into a Docker image can easily balloon to 500MB or more, making deployments slower and less efficient. Standalone output for Docker: what developers should know covers one of the most effective strategies we use in production to shrink those images down by hundreds of megabytes without sacrificing functionality.

What is standalone output and why it matters

When you build a Next.js application with the default configuration, the output directory contains everything—source files, node_modules, build artifacts, and more. Docker then copies all of that into your image layer, which balloons the final size unnecessarily. The output: 'standalone' configuration in next.config.js tells Next.js to generate only the minimal set of files required to run your application in production.

We saw this firsthand on an e-commerce platform where the default approach produced 800MB images. Switching to standalone output dropped that to around 150MB—a 5x improvement. That difference compounds across deployments, staging environments, and CI/CD pipelines. Faster image pulls from registries, lower storage costs, and quicker deployment times add up.

The standalone mode works by analyzing your application's dependencies and runtime requirements, then bundling only what's needed. It excludes development dependencies, unused node_modules, source files, and other build artifacts. For Next.js applications running in containerized environments, this is often the right trade-off.

Configuring output: 'standalone' in next.config

Enabling standalone output is straightforward. Open your next.config.js file and add the configuration:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
};

module.exports = nextConfig;

That single line tells Next.js to restructure the build output. Run npm run build or yarn build and you'll notice the .next directory changes. Instead of a large node_modules directory nested inside, Next.js generates a slimmer structure optimized for containerization.

The standalone output creates a directory at .next/standalone containing everything you need to run the app. It also includes a copy of node_modules with only production dependencies. This is the directory you'll reference in your Dockerfile.

Copies only the files needed to run

Standalone output uses intelligent dependency analysis to include only production dependencies. It walks through your code, traces imports, and identifies which packages from node_modules are actually used at runtime. Development-only packages like TypeScript, ESLint, testing libraries, and build tools are excluded automatically.

On a SaaS platform we worked on, the difference was dramatic. The full node_modules directory was 350MB; the standalone version's node_modules was 42MB. That's not because we were using fewer packages—it's because we were only keeping the ones the production server actually loads.

This analysis also works with dynamic imports and conditional requires, though you should test thoroughly if your app uses unusual patterns. Standard use cases like React, Next.js APIs, database drivers, and utility libraries are handled correctly out of the box.

Copy public and .next/static separately in your Dockerfile

When moving to standalone output, your Dockerfile needs adjustment. You can't simply copy the entire project anymore. Instead, you copy the standalone build artifacts in specific layers, which also gives you better Docker cache optimization.

Here's a production-grade example:

FROM node:20-alpine AS base
WORKDIR /app

FROM base AS dependencies
COPY package*.json ./
RUN npm ci --only=production

FROM base AS builder
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM base AS runtime
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

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

The key steps here: first, we build the application normally in a builder stage. Then in the runtime stage, we copy .next/standalone which includes the production server and minimal node_modules. We then explicitly copy .next/static (your optimized assets) and public (static files like images and favicons) as separate layers.

This separation matters for two reasons. First, Docker caches layers independently. If you change a static asset or image in public, only that layer rebuilds—the node_modules and server code stay cached. Second, it makes your image structure explicit and easier to debug.

The standalone output creates a server.js file automatically. That's your entry point for running Next.js in production without needing the full next command-line tool.

Images often drop by hundreds of megabytes

The size reduction varies by application, but we consistently see 50-80% improvements. A trading platform we worked on went from 620MB down to 110MB. A travel booking SaaS went from 480MB to 95MB. These aren't theoretical—they're real deployments running billions of requests monthly.

Why such dramatic reductions? Several factors combine:

• No development dependencies: TypeScript compiler, build tools, and test frameworks stay out of the image.
• No source files: Only compiled/optimized code makes it into the container.
• Lean node_modules: Only runtime dependencies, often 5-10 packages instead of hundreds.
• Optimized static assets: Your .next/static is already tree-shaken and minified.

The compounding benefit becomes clear in practice. Each 500MB reduction means 500MB less to pull across the network on every deployment. On a platform deploying 20 times daily, that's 10GB of unnecessary bandwidth daily. Over a year, the infrastructure cost savings alone justify the migration.

We also see faster startup times in Kubernetes and other orchestrators, particularly in autoscaling scenarios where instances spin up frequently. A 110MB image starts serving traffic noticeably faster than a 620MB one.

Common mistakes

Forgetting to copy public and .next/static: The biggest mistake we see is copying only the standalone directory and skipping the public assets. Your site will load but images, favicons, and other static files won't appear. Always copy these explicitly.

Pointing to the wrong entry file: Ensure your CMD in the Dockerfile references the actual location of server.js. In the Dockerfile above, it's at the root because we copied .next/standalone to ./. If you copy to a subdirectory, adjust the path.

Missing environment variables: The standalone output is self-contained, but environment variables still need to be passed at runtime. Set NODE_ENV, database URLs, API keys, and other config through Docker environment variables or a .env.local file mounted into the container.

Assuming all third-party libraries work: Most do, but some packages with unusual require patterns or native bindings might not bundle correctly. Test your specific dependencies in a staging deployment before going to production. Packages that dynamically require modules based on environment variables are particularly worth testing.

Not using multi-stage builds: If you're copying the builder stage output directly into a runtime image without a separate builder stage, you defeat most of the size benefits. Always separate build-time dependencies from runtime.

Key takeaways

• Set output: 'standalone' in next.config.js to generate a minimal production-ready build.
• Standalone output includes only production dependencies and compiled code, typically reducing image size by 50-80%.
• In your Dockerfile, copy .next/standalone for the server, then explicitly copy .next/static and public for assets.
• Use multi-stage Docker builds to keep build tools and development dependencies out of your final image.
• Always test with your actual dependencies before deploying to production—most libraries work, but verify edge cases.
• The size and speed improvements compound across deployments, CI/CD pipelines, and orchestration scenarios.