Static Export in Next.js: Host Your Site Anywhere
Use output: export to turn a Next.js site into plain HTML, CSS, and JavaScript you can host on GitHub Pages, Netlify, or any server. Limits and setup inside.
By UndieGravity, , 1 min read
Not every Next.js site needs a server. A portfolio, a landing page, or documentation can be exported as static files and hosted on any web server or free static host. Next.js calls this a static export.
Turn it on
// next.config.ts
const nextConfig = {
output: "export",
images: { unoptimized: true },
};
export default nextConfig;Run npm run build and Next.js writes the site to an out/ folder. Upload that folder anywhere that serves files.
What still works
- Server Components that fetch data at build time.
- Client Components with state and effects.
- Dynamic routes, as long as
generateStaticParamslists every page. - Route handlers with
GETthat return static data, such as an RSS feed.
What does not
Anything that needs a server at request time is unavailable in a static export:
- Reading cookies or headers, and dynamic routes without
generateStaticParams. - Server Actions and incremental revalidation.
redirects,rewrites, andheadersfromnext.config. Configure them on your host instead.- The default image optimizer. Use
images.unoptimized: trueor a custom loader that points at an image CDN. - The
proxy.tsfile.
Hosting on GitHub Pages
A project site on GitHub Pages lives under a sub path, like username.github.io/my-site. Tell Next.js about it so links and assets resolve:
const nextConfig = {
output: "export",
basePath: "/my-site",
images: { unoptimized: true },
trailingSlash: true,
};trailingSlash: true makes Next.js write about/index.html instead of about.html, which plain static servers handle more reliably.
When to choose it
- Choose static export for content that changes only when you deploy, and when you want the cheapest, simplest hosting.
- Choose a server deployment (Vercel, Netlify, or Node.js) when you need forms with Server Actions, per-user pages, or content that updates without a rebuild.