ISR

Core Idea

Incremental Static Regeneration atualiza páginas estáticas sem rebuild completo do site: serve a página cacheada instantaneamente e regenera em background após o período de revalidate.

Key Concepts

• revalidate (em getStaticProps): tempo em segundos; após esse período, a próxima request ainda recebe a versão cacheada (stale), mas dispara regeneração em background pra requests seguintes.
• fallback: 'blocking' (em getStaticPaths): paths não gerados no build são renderizados sob demanda na primeira request; se não existir, retorna 404.
• On-demand revalidation (res.revalidate(path)): chamada numa API Route pra forçar regeneração de um path específico sem esperar o revalidate expirar; usa o path real, não um path reescrito.
• Erro em getStaticProps durante regeneração background: a última página gerada com sucesso continua sendo servida; Next.js tenta getStaticProps de novo na próxima request.
• NEXT_PRIVATE_DEBUG_CACHE=1: env var que loga hits/misses de cache ISR no console do servidor, útil pra debug.

Code Examples

export const getStaticProps: GetStaticProps<Props> = async ({ params }) => {
  const post = await fetch(`https://api.vercel.app/blog/${params.id}`).then((res) => res.json())
  return {
    props: { post },
    // Next.js will invalidate the cache when a
    // request comes in, at most once every 60 seconds.
    revalidate: 60,
  }
}

• O que demonstra: revalidate: 60 como TTL de regeneração em background.

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: 'Invalid token' })
  }
  try {
    await res.revalidate('/posts/1')
    return res.json({ revalidated: true })
  } catch (err) {
    return res.status(500).send('Error revalidating')
  }
}

• O que demonstra: revalidação sob demanda protegida por secret token, disparada externamente (ex.: webhook do CMS).

Reference Tables

Deployment Option	ISR Suportado
Node.js server	Sim
Docker container	Sim
Static export	Não
Adapters	Depende da plataforma

Version	Changes
v14.1.0	cacheHandler customizado estável
v12.2.0	On-Demand ISR estável (Pages Router)
v9.5.0	ISR introduzido (Pages Router)

Anti-patterns

• Revalidar path reescrito em vez do path real: res.revalidate precisa do path efetivo (ex. /posts/1), não de um rewrite tipo /post-1; Proxy não executa em requests de on-demand ISR.
• Combinar ISR com Static Export: incompatíveis, ISR exige runtime Node.js.
• Usar revalidate fixo junto com on-demand revalidation sem necessidade: se on-demand já cobre o caso, revalidate pode ficar de fora (default false, sem revalidação por tempo).

Key Takeaways

1. ISR combina performance de estático com atualização sem rebuild completo.
2. Erro em regeneração nunca derruba a página, o Next.js mantém a última versão boa e tenta de novo depois.
3. On-demand revalidation via API Route é mais preciso que esperar o revalidate por tempo.
4. ISR não funciona com output: export nem fora do runtime Node.js.

Connects To

• ch302 Draft Mode: alternativa pra ver conteúdo não publicado sem esperar revalidação.