What is static export (output: 'export') in Next.js and what does it not support?

Q: What is static export (output: 'export') in Next.js and what does it not support?

**Target Audience:** Developers preparing for Next.js interviews — assumes the basics of App Router rendering (static vs dynamic routes). **Difficulty:** Medium > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js 16.4.2 docs shipped with the package and, in the **Verified** section, against lab builds with `output: "export"`, a plain static file server and a Chromium browser. ## 1. Why This Even Matters — A Story First A normal Next.js app is a restaurant with a kitchen: some dishes are prepared in advance, others are cooked when you order. Static export is a vending machine. Everything is prepared before the machine is stocked, and the machine itself cannot cook. That makes it cheap, fast and able to sit anywhere — a CDN, an S3 bucket, GitHub Pages — but you cannot ask it for something it does not already contain, and it cannot read who is standing in front of it. "W

The problem

Question presented to candidate: "We want to host a Next.js marketing site on plain static hosting — an S3 bucket behind a CDN, no Node server. How does static export work, what do we get in the output, and which Next.js features will we lose?"

What a strong answer should cover:

output: "export" in next.config makes next build write HTML, CSS, JS and RSC payload files to out/, one HTML file per route; it replaced the next export command (removed in v14).
Server Components still run, but only at build time; Client Components hydrate and client navigation works like an SPA. GET Route Handlers with force-static become static files.
Dynamic routes need generateStaticParams; anything per-request is unsupported: cookies()/headers(), Server Actions, ISR, Draft Mode, rewrites/redirects/headers config, proxy, request-reading Route Handlers, intercepting routes, default image optimization.
Some of these fail the build, but some only warn or pass silently (rewrites, proxy, revalidate, the default image loader in the lab), so test the output on a static server.
Hosting detail: map /about to about.html (or use trailingSlash: true) and serve 404.html.

Clarifying questions expected:

"Does any page need per-user data or form submissions to our own backend?" — that needs a server or an external API.
"How often does content change?" — every change needs a rebuild and redeploy, there is no ISR.

Code / implementation expected: Yes — the config and a dynamic route with generateStaticParams.

nextjs
static-export
deployment
next-config

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Developers preparing for Next.js interviews — assumes the basics of App Router rendering (static vs dynamic routes). Difficulty: Medium

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js 16.4.2 docs shipped with the package and, in the Verified section, against lab builds with output: "export", a plain static file server and a Chromium browser.

1. Why This Even Matters — A Story First

A normal Next.js app is a restaurant with a kitchen: some dishes are prepared in advance, others are cooked when you order. Static export is a vending machine. Everything is prepared before the machine is stocked, and the machine itself cannot cook. That makes it cheap, fast and able to sit anywhere — a CDN, an S3 bucket, GitHub Pages — but you cannot ask

The solution is hidden so you can try first

9 min read · 9 sections

Read the code

next.config.ts for a static export

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",          // next build writes plain files to out/
  trailingSlash: true,       // optional: /about -> out/about/index.html, easier on plain static hosts
  images: { unoptimized: true }, // or a custom loader; the default optimizer needs a server
  // basePath: "/my-repo",   // e.g. for GitHub Pages project sites
};

export default nextConfig;

Pages and a Route Handler that export cleanly

// app/blog/[slug]/page.tsx — every dynamic path must be listed at build time
export function generateStaticParams() {
  return [{ slug: "hello" }, { slug: "world" }];
}

export default async function Post({ params }: PageProps<"/blog/[slug]">) {
  const { slug } = await params;
  return <h1>Post: {slug}</h1>;
}

// app/data.json/route.ts — a GET Route Handler becomes a static file (out/data.json)
export const dynamic = "force-static";

export function GET() {
  return Response.json({ name: "Lee" });
}

// app/ui/Clock.tsx — browser-only work happens after hydration
"use client";
import { useEffect, useState } from "react";

export default function Clock() {
  const [now, setNow] = useState<string | null>(null);
  useEffect(() => setNow(new Date().toLocaleTimeString()), []);
  return <p>Local time: {now ?? "..."}</p>;
}

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.