Static Exports

Core Idea

output: 'export' gera um site estático (HTML/CSS/JS por rota) que pode ser hospedado em qualquer servidor de arquivos estáticos, sem Node.js, útil para começar como SPA/site estático e evoluir depois.

Key Concepts

• output: 'export': opção em next.config.js que ativa o modo de export estático.
• trailingSlash: opcional, transforma /me em /me/ e emite /me.html como /me/index.html.
• skipTrailingSlashRedirect: evita o redirect automático /me → /me/, preservando o href original.
• distDir: muda o diretório de saída (padrão out).
• Custom image loader: necessário para Image Optimization funcionar em export estático (otimização acontece em runtime, não no build).

Code Examples

const nextConfig = {
  output: 'export',
  images: {
    loader: 'custom',
    loaderFile: './my-loader.ts',
  },
}

• O que demonstra: habilitar export estático com loader de imagem customizado (ex. Cloudinary) já que o loader padrão exige servidor.

export default function cloudinaryLoader({ src, width, quality }: { src: string; width: number; quality?: number }) {
  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`]
  return `https://res.cloudinary.com/demo/image/upload/${params.join(',')}${src}`
}

• O que demonstra: implementação de um loader de imagem para serviço externo (Cloudinary) sob static export.

Reference Tables

Suportado	Não suportado
Dynamic Routes com getStaticPaths	Internationalized Routing
Prefetching com next/link	API Routes
Dynamic Imports	Rewrites / Redirects / Headers (config)
CSS Modules, styled-jsx	Proxy
Client-side data fetching	Incremental Static Regeneration
getStaticProps / getStaticPaths	Image Optimization com loader padrão
—	Draft Mode
—	getStaticPaths com fallback: true ou 'blocking'
—	getServerSideProps

Versão	Mudança
v14.0.0	next export removido em favor de "output": "export"
v13.4.0	App Router estável adiciona suporte aprimorado (RSC, Route Handlers)
v13.3.0	next export deprecado, substituído por "output": "export"

Anti-patterns

• Usar getServerSideProps ou API Routes esperando export estático funcionar: não são suportados; requerem servidor Node.
• Esquecer o custom image loader: sem ele, next/image não otimiza nada em static export.

Key Takeaways

1. Static export gera um arquivo HTML por rota dentro de out/, deployável em qualquer host estático (inclusive GitHub Pages).
2. Qualquer feature que dependa de request em runtime (Proxy, ISR, API Routes, getServerSideProps) fica fora do escopo.
3. Para nginx, é preciso configurar try_files e rewrites manuais para rotas dinâmicas sem trailingSlash: true.
4. next export como comando separado foi removido desde a v14; hoje é sempre via output: 'export'.

Connects To

• Self-Hosting: contraste, quando um servidor Node é necessário para Proxy/ISR/Image Optimization completos.
• next/image: precisa de loader customizado neste modo.