prefetch

Core Idea

Route segment config que controla como um segmento é prefetchado durante navegação client-side, servindo como um "teto de custo" que qualquer <Link> apontando para aquele destino deve respeitar.

Key Concepts

• prefetch: export 'auto' | 'partial' | 'force-disabled'; só funciona com cacheComponents habilitado; não pode ser usado em Client Component.
• 'auto' (default, implícito): comportamento gerenciado pelo framework via partialPrefetching; não escreva explicitamente.
• 'partial': opta o segmento em Partial Prefetching sem ligar a flag global; <Link> padrão carrega o App Shell; <Link prefetch={true}> resolve dados de URL completos (params, searchParams).
• 'force-disabled': nunca prefetch esse segmento; útil para páginas raramente visitadas atrás de autenticação.

Code Examples

export const prefetch = 'partial'

export default function Page() {
  return <div>...</div>
}

• O que demonstra: adoção incremental de Partial Prefetching por rota, sem ligar a flag global.

Reference Tables

Valor	Efeito no <Link> padrão	Efeito no <Link prefetch={true}>
'partial'	Carrega App Shell	Resolve params/searchParams/URL completa + conteúdo em cache
'force-disabled'	Pula dados do segmento	Pula dados do segmento (só metadados de rota ainda podem ser prefetched)

Anti-patterns

• Escrever prefetch = 'auto' explicitamente: é o default e equivale a omitir o export.
• Usar prefetch em Client Component: não suportado.
• Achar que 'force-disabled' bloqueia toda pré-busca: metadados da rota ainda podem ser prefetched; só os dados do segmento (e mais fundo) são omitidos.

Key Takeaways

1. Use 'partial' para migrar app inteiro para Partial Prefetching rota a rota; depois que tudo estiver migrado, ligue a flag global partialPrefetching e remova os exports por rota.
2. <Link prefetch={false}> sempre pula prefetch no nível do link, independente da config do destino.
3. Segmentos mais fundos com 'force-disabled' ainda podem ser incluídos numa resposta de per-link prefetch se o link usar prefetch={true} num ancestral.
4. Páginas totalmente estáticas servem prefetch do cache estático/CDN; páginas com dados não-estáticos (cookies, headers) custam CPU do servidor a cada prefetch.

Connects To

• instant: outra config de segmento relacionada a navegação instantânea, também exclusiva de Cache Components.
• Link component (prefetch prop): interage diretamente com esta config de segmento.