UndieGravity LogoUndiegravity

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 generateStaticParams lists every page.
  • Route handlers with GET that 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, and headers from next.config. Configure them on your host instead.
  • The default image optimizer. Use images.unoptimized: true or a custom loader that points at an image CDN.
  • The proxy.ts file.

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.

Keep reading

Next.js

Next.js 16: What Changed and How to Upgrade

Next.js 16 makes Turbopack the default, renames middleware to proxy, requires async request APIs, and changes caching. Here is what to update first.

, 2 min read