Static Export

Pure HTML/CSS/JS

Set output: 'export' and next build generates an out/ directory of static files. Drop them on any static host (S3, GitHub Pages, Cloudflare Pages, plain nginx).

What you give up

Works	Doesn't work
Server Components (build-time)	Server Actions
Static Route Handlers (GET)	Proxy / dynamic Route Handlers
Client Components + SWR	ISR / on-demand revalidation
`generateStaticParams`	`cookies()`, `headers()`
`next/image` with custom loader	Default image optimizer

When to use it

Marketing sites, docs, portfolios — anything that's pure content. The cheapest deploy possible: any CDN with no compute.

Choose static export only when every required route can be completed at build time or in the browser against an external API. Inventory cookies, headers, dynamic params, mutations, revalidation, redirects, image behavior, and secret-backed reads before committing to the host. Static hosts differ in path handling, so test extensionless URLs and trailing slashes. A file that opens locally must also return the expected response after a direct CDN refresh.

Client-side fetching does not magically recover all server features. It changes first-load behavior, exposes a public API surface, and moves authorization and caching concerns elsewhere. Static hosting is an architectural boundary, not a deployment toggle. Build the export from a clean checkout, serve only the out/ directory, and navigate directly to every route with JavaScript both enabled and disabled. Test refreshes, 404s, asset paths, metadata, client API failures, and any host-specific fallback rules.

Code

Configure and build·ts

// next.config.ts
import type { NextConfig } from 'next';
const config: NextConfig = {
  output: 'export',
  trailingSlash: true,    // optional: /about/ instead of /about
  images: { unoptimized: true }, // or supply a custom loader
};
export default config;

Build·bash

npm run build

# Output:
# out/
# ├── index.html
# ├── about/index.html
# ├── blog/post-1/index.html
# └── _next/...

# Deploy:
npx serve out                # local test
aws s3 sync out s3://bucket   # production

Pure HTML/CSS/JS

What you give up

When to use it

Code

External links

Exercise

Progress

Comments 0