SSR vs SSG com Claude Code: renderização em Next.js e Astro

Alinhe os termos primeiro

Escolher entre SSR e SSG não é apenas escolher o que parece mais rápido. SSR significa server-side rendering: o servidor gera o HTML quando uma requisição chega. SSG significa static site generation: o HTML é gerado no build e servido por CDN ou hospedagem estática. ISR, Incremental Static Regeneration, fica no meio: a página é servida como estática, mas pode ser regenerada por tempo ou por evento.

Um erro comum no Next.js App Router é achar que Server Component sempre significa SSR a cada requisição. Não significa. Na documentação atual de Dynamic Route Segments, os exemplos TypeScript tratam params como Promise. Quando você precisa indicar que o render deve esperar uma requisição real, a API atual é connection.

Se você pedir ao Claude Code apenas “deixe esta página mais rápida”, ele pode estatizar demais e congelar estoque, busca ou UI de membros. Se pedir SSR para tudo, TTFB e custo de servidor podem subir. O caminho prático é pedir uma matriz de rotas: frescor dos dados, personalização, frequência de atualização, impacto em monetização e comando de verificação.

Comparação e casos reais

Pergunta	SSG	ISR	SSR
Quando o HTML é gerado	Build	Build e revalidação	Requisição
Melhor para	Artigos, docs, landing pages	Produtos, categorias, notícias	Painéis, busca, carrinho
Frescor dos dados	Snapshot do build	Por tempo ou evento	Quase atual
Custo de entrega	Baixo	Médio	Geralmente maior
Falha comum	Builds longos, conteúdo velho	Resposta antiga por pouco tempo	Lento sem cache

Caso 1: blog ou documentação. Se corpo, OGP, links internos e CTA ficam fixos na publicação, SSG é a escolha mais limpa. Você reconstrói quando o artigo muda. Se também quiser reduzir JavaScript, veja code splitting com Claude Code.

Caso 2: página de produto. Preço, disponibilidade e ordem de categoria podem mudar a cada poucos minutos, mas a maioria dos visitantes deve receber uma resposta rápida. ISR combina bem. O guia oficial de ISR no Next.js explica que ISR funciona com Node.js runtime e não funciona com static export.

Caso 3: painel de conta. Cookies, permissões, cobrança, notificações e recomendações privadas dependem da requisição. Trate como SSR e defina headers de cache com cuidado. Se a equipe estiver avaliando edge para rotas dinâmicas, leia edge computing com Claude Code depois de decidir quais dados podem ir para perto do usuário.

Exemplo SSR em Next.js

Este exemplo pode ser copiado para um projeto Next.js App Router. Ele usa dummyjson.com, então não precisa de API key. connection() e cache: "no-store" deixam claro no review que o comportamento é por requisição.

// app/products/[id]/page.tsx
import { notFound } from "next/navigation";
import { connection } from "next/server";

type Product = {
  id: number;
  title: string;
  price: number;
  stock: number;
  updatedAt: string;
};

async function getProduct(id: string): Promise<Product | null> {
  await connection();

  const res = await fetch(`https://dummyjson.com/products/${id}`, {
    cache: "no-store",
  });

  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`Failed to load product: ${res.status}`);

  const data = (await res.json()) as {
    id: number;
    title: string;
    price: number;
    stock: number;
    meta?: { updatedAt?: string };
  };

  return {
    id: data.id,
    title: data.title,
    price: data.price,
    stock: data.stock,
    updatedAt: data.meta?.updatedAt ?? new Date().toISOString(),
  };
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProduct(id);

  if (!product) notFound();

  return (
    <main>
      <h1>{product.title}</h1>
      <p>Price: ${product.price.toLocaleString("en-US")}</p>
      <p>Stock: {product.stock}</p>
      <p>Updated: {new Date(product.updatedAt).toLocaleString("pt-BR")}</p>
    </main>
  );
}

A armadilha principal é colocar cookies() ou headers() em um layout compartilhado por conveniência. Essas APIs dependem da requisição e podem tornar dinâmicas rotas que antes eram estáticas. Se esse layout envolve artigos, você perde SSG sem perceber. Peça ao Claude Code para listar as rotas afetadas antes de aceitar o patch.

Separar SSG, ISR e export estático

SSG e ISR podem parecer iguais para o visitante, mas a operação é diferente. SSG atualiza no build. ISR atualiza depois de uma janela de tempo ou evento. O export estático usa output: "export" para gerar uma pasta out, que pode ser servida sem servidor Node.js. O guia oficial de Static Exports explica que next build pode gerar um HTML por rota para hospedagem estática.

// app/catalog/[id]/page.tsx
import { notFound } from "next/navigation";

export const revalidate = 3600;

type Product = {
  id: number;
  title: string;
  description: string;
};

export async function generateStaticParams() {
  return ["1", "2", "3"].map((id) => ({ id }));
}

async function getProduct(id: string): Promise<Product | null> {
  const res = await fetch(`https://dummyjson.com/products/${id}`, {
    next: { revalidate: 3600, tags: [`product:${id}`] },
  });

  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`Failed to load product: ${res.status}`);

  return (await res.json()) as Product;
}

export default async function CatalogPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProduct(id);

  if (!product) notFound();

  return (
    <article>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
    </article>
  );
}

// next.config.mjs
const nextConfig = {
  output: "export",
  images: {
    unoptimized: true,
  },
};

export default nextConfig;

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "export:check": "next build && npx serve out"
  }
}

Não trate export estático e ISR como opções intercambiáveis. Export estático é para hospedagem estática. Se a rota precisa de cookies, revalidação sob demanda, Server Functions ou SSR real, planeje um runtime de servidor. Antes de Claude Code escrever código, diga se o alvo é Cloudflare Pages estático, container Node, Vercel, Netlify ou outro ambiente.

Astro estático e on-demand

Astro parte de geração estática por padrão. A documentação oficial de Astro on-demand rendering diz que páginas, rotas e endpoints são prerenderizados no build por padrão. Depois de adicionar um adapter de servidor, uma rota pode usar export const prerender = false para renderizar sob demanda.

---
// src/pages/docs/[slug].astro
export async function getStaticPaths() {
  const docs = [
    { slug: "ssr", title: "SSR guide" },
    { slug: "ssg", title: "SSG guide" },
  ];

  return docs.map((doc) => ({
    params: { slug: doc.slug },
    props: { doc },
  }));
}

const { doc } = Astro.props;
---

<html lang="pt-BR">
  <body>
    <article>
      <h1>{doc.title}</h1>
      <p>This page was generated at build time.</p>
    </article>
  </body>
</html>

---
// src/pages/account.astro
export const prerender = false;

const session = Astro.cookies.get("session")?.value;
const name = session ? "Masa" : "Guest";

Astro.response.headers.set("Cache-Control", "private, no-store");
---

<html lang="pt-BR">
  <body>
    <h1>Account</h1>
    <p>Hello, {name}.</p>
  </body>
</html>

A falha comum no Astro é esquecer o adapter. A página pode parecer correta localmente, mas on-demand rendering precisa de runtime de servidor em produção. Peça ao Claude Code para revisar astro.config.mjs, plataforma de deploy e cada override de prerender.

Comandos de verificação e prompt

A estratégia de renderização não é validada só lendo código. Verifique build output, headers, logs de cache e métricas como TTFB e LCP. Para ISR, a documentação do Next.js recomenda testar o comportamento de produção com next build e next start.

# Next.js: production behavior
npm run build
npm run start

# In another terminal
curl -I http://localhost:3000/catalog/1
curl -I http://localhost:3000/products/1

# ISR cache debugging
NEXT_PRIVATE_DEBUG_CACHE=1 npm run start

# Astro
npm run build
npm run preview

O prompt precisa pedir registro de decisão, não só código:

Goal: classify every route in a Next.js/Astro site as SSR, SSG, ISR, or static export.

Inspect:
- app/ or src/pages/ routes
- cookies(), headers(), searchParams, connection(), cache: "no-store"
- generateStaticParams(), revalidate, output: "export", Astro prerender
- monetization pages, member pages, articles, product pages, and search pages

Constraints:
- Do not break SEO metadata or internal links
- Keep npm run build passing before and after
- Return a table with the chosen strategy, reason, touched files, and verification command

Armadilhas concretas

Primeira: colocar conteúdo específico do usuário dentro de um artigo estático. Nome do membro, recomendações privadas e preços ocultos não devem entrar no HTML SSG. Mantenha o artigo estático e mova personalização para um componente cliente ou seção claramente dinâmica.

Segunda: configurar intervalos ISR curtos demais. revalidate = 1 muitas vezes devolve o custo para o servidor. Se você precisa de precisão, use revalidação sob demanda. Se precisa de tempo real, use SSR.

Terceira: escolher export estático e depois adicionar recursos de servidor. Auth, UI baseada em cookies, Server Route Handlers e ISR exigem runtime. Hospedagem estática é excelente, mas não substitui servidor.

Quarta: aceitar a proposta do Claude Code só porque parece rápida. Em um site monetizado, performance é apenas parte da qualidade. OGP, dados estruturados, links internos, anúncios, tracking de CTA, LCP e CLS também importam. Depois da decisão, use otimização de performance com Claude Code.

Recomendação pensando em monetização

Para um negócio de conteúdo como ClaudeCodeLab, use SSG por padrão em artigos, tutoriais, comparativos e páginas de entrada. Use ISR em catálogos, categorias e superfícies que toleram conteúdo levemente antigo. Use SSR em contas, busca, carrinho, contexto de checkout e qualquer rota com dados privados da requisição.

Para começar com um fluxo prático, baixe o cheatsheet gratuito de Claude Code. Para templates e pacotes de implementação, veja a página de produtos. Se a equipe precisa alinhar estratégia de rotas, permissões, code review, analytics e treinamento de deploy, comece por treinamento e consultoria Claude Code.

O que verifiquei na prática

Nesta atualização, verifiquei as páginas oficiais de Next.js Dynamic Route Segments, connection, ISR, Static Exports, Astro on-demand rendering e Claude Code overview. No fluxo de conteúdo de Masa, a divisão mais estável foi SSG para artigos, ISR para produtos e categorias, SSR para conta e busca. O passo mais valioso com Claude Code foi pedir a matriz de rotas antes de mexer no código. Ela expôs cedo uso acidental de cookies em páginas estáticas e deixou cada rota com motivo e comando de verificação.