Capítulo 159 de 456

fetch

Core Idea

Next.js estende a Web fetch() API para permitir que cada requisição server-side defina sua própria semântica de cache persistente e revalidação, integrando fetch diretamente ao sistema de cache do framework.

Key Concepts

  • options.cache: controla como a requisição interage com o cache persistente do Next.js (diferente do HTTP cache do browser).
  • auto no cache (default): busca do servidor remoto a cada request em dev; em next build busca uma vez porque a rota é prerenderizada estaticamente; se Request-time APIs forem detectadas, busca a cada request.
  • no-store: sempre busca do servidor remoto, mesmo sem Request-time APIs na rota.
  • force-cache: procura por match no cache server-side (URL + method + headers + body); se fresco, retorna do cache; senão busca e atualiza (só respostas 200 são armazenadas).
  • options.next.revalidate: define tempo de vida em segundos (false = indefinido, 0 = sem cache, number = segundos).
  • options.next.tags: define tags de cache para revalidação sob demanda via revalidateTag (máx. 128 tags, 256 caracteres cada).
  • Memoização: fetch GET com mesma URL/opções é memoizado automaticamente durante um único server render pass (não vale para Route Handlers, que ficam fora da árvore React).

Code Examples

export default async function Page() {
  let data = await fetch('https://api.vercel.app/blog')
  let posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
  • O que demonstra: fetch básico dentro de Server Component com async/await.
fetch(`https://...`, { next: { revalidate: 3600, tags: ['collection'] } })
  • O que demonstra: cache por 1 hora com tag para revalidação on-demand via revalidateTag.
const { signal } = new AbortController()
fetch(url, { signal })
  • O que demonstra: opt-out da memoização passando um AbortController signal.

Anti-patterns

  • Combinar revalidate com cache: 'no-store': opções conflitantes; ambas são ignoradas e um warning é impresso em dev.
  • Esperar dados frescos em dev com auto no cache/no-store sob HMR: o HMR cache do Next.js intercepta essas respostas entre refreshes; limpa só em navegação ou reload completo.

Key Takeaways

  1. Se um fetch individual define revalidate menor que o padrão da rota, o intervalo de revalidação de toda a rota diminui.
  2. Entre múltiplos fetches com a mesma URL na mesma rota, o menor revalidate prevalece.
  3. Draft Mode bypassa o cache de fetch inteiramente (sem leitura nem escrita).
  4. Em dev, header cache-control: no-cache (típico de hard refresh) ignora cache, next.revalidate e next.tags, servindo direto da fonte.

Connects To

  • cacheLife / cacheTag: mecanismo equivalente para use cache, com granularidade e perfis mais ricos que fetch puro.
  • revalidateTag: função usada para invalidar dados marcados com next.tags.
  • serverComponentsHmrCache: config que controla o comportamento de cache de fetch durante HMR em dev.
AnteriordraftModePróximoforbidden