Capítulo 82 de 456

Static Exports

Core Idea

output: 'export' gera um arquivo HTML por rota (mais CSS/JS), permitindo hospedar Next.js em qualquer servidor estático — sem servidor Node.js — como caminho de início ou upgrade progressivo.

Key Concepts

  • output: 'export': opção em next.config.js que ativa a exportação estática; next build gera a pasta out com os assets finais.
  • trailingSlash: muda links /me → /me/ e emite /me.html → /me/index.html.
  • skipTrailingSlashRedirect: previne o redirect automático /me → /me/, preservando o href original.
  • distDir: muda o diretório de saída de out para outro nome.
  • Server Components em static export: rodam durante o next build (como SSG tradicional); geram HTML estático + payload estático para navegação — sem mudanças necessárias, exceto se usarem dynamic server functions.
  • Route Handlers estáticos: só suportam GET; precisam de export const dynamic = 'force-static' explícito para serem prerenderizados durante o build, gerando arquivo estático (ex. data.json).
  • Image Optimization com static export: exige images.loader: 'custom' + loaderFile apontando pra um loader customizado (ex. Cloudinary) — o loader padrão do next/image não é suportado.

Code Examples

const nextConfig = {
  output: 'export',
}
module.exports = nextConfig
  • O que demonstra: configuração mínima para habilitar static export.
export const dynamic = 'force-static'

export async function GET() {
  return Response.json({ name: 'Lee' })
}
  • O que demonstra: Route Handler explicitamente marcado como estático, gerando data.json no build.
location / {
    try_files $uri $uri.html $uri/ =404;
}
location /blog/ {
    rewrite ^/blog/(.*)$ /blog/$1.html break;
}
  • O que demonstra: regras de rewrite no Nginx para servir os arquivos .html gerados corretamente.

Reference Tables

VersãoMudança
v14.0.0next export removido em favor de "output": "export"
v13.4.0App Router (Stable) ganha suporte estendido a static export, incluindo RSC e Route Handlers
v13.3.0next export depreciado, substituído por "output": "export"

Anti-patterns

  • Usar Cookies, Rewrites, Redirects (config), Headers (config), Proxy, ISR, Draft Mode, Server Actions, Intercepting Routes ou Dynamic Routes sem generateStaticParams()/com dynamicParams: true: nenhum desses é suportado em static export — usar qualquer um deles com next dev sob export gera erro (equivalente a export const dynamic = 'error' no root layout).
  • Acessar window/localStorage/navigator fora de useEffect em Client Component: essas Web APIs não existem no servidor durante o prerender do build.

Key Takeaways

  1. output: 'export' é a substituição atual do antigo next export (removido na v14).
  2. Route Handlers em static export só suportam GET e precisam do marcador explícito force-static.
  3. Image Optimization funciona em static export apenas com loader customizado — o padrão exige servidor.
  4. A lista de features não suportadas é longa (cookies, ISR, Server Actions, Proxy, etc.) — vale checar antes de decidir por export puro.

Connects To

  • SPAs (ch081): static export é uma forma de construir uma strict SPA com Next.js.
  • Self-Hosting (ch078): alternativa a static export quando se precisa de features de servidor.
AnteriorSPAsPróximoStreaming