TanStack Query (React Query) x Next.js cache features | TanStack | React

• TanStack Query (React Query) x Next.js cache features | TanStack | React

---

	TanStack Query	Next.js (SSR/ISR/cache)
Onde	Navegador (cliente)	Servidor ou edge
Quando	Após a hidratação da app	Antes da resposta ser enviada ao cliente
Cache	Em memória (volátil)	Persistente, via build/infra
Dados	Dinâmicos por natureza	Estáticos ou com revalidação
Controle	Via hooks e configuração React	Via getStaticProps, fetch, headers
Persistência	Não, a menos que implementado	Sim, por design

---

Quando usar TanStack Query e quando usar os recursos de cache do Next.js

Esta documentação define critérios claros para decidir entre TanStack Query e cache nativo do Next.js, especialmente no contexto do App Router e Server Components.

O objetivo é evitar overengineering, gambiarra arquitetural e uso incorreto das ferramentas.

---

Natureza de cada solução

Next.js Cache Features

Os recursos de cache do Next.js atuam no lado do servidor e são integrados ao modelo de Server Components.

Principais características:

• Executa no server
• Atua no fetch
• Otimizado para SSR, SSG e ISR
• Não depende de JavaScript no navegador

Ferramentas principais:

• fetch com cache e revalidate
• revalidatePath
• revalidateTag

---

TanStack Query

TanStack Query é uma solução para gerenciamento de estado remoto no navegador.

Principais características:

• Executa no client
• Baseado em hooks
• Mantém cache no navegador
• Reativo a interações do usuário

Funcionalidades típicas:

• refetch automático
• optimistic updates
• polling
• sincronização de estado com UI

---

Quando usar Next.js Cache Features

Use os recursos de cache do Next.js quando os dados:

• São apenas leitura
• Dependem da URL
• Precisam de SEO
• Não mudam por interação direta do usuário
• Podem ser cacheados no servidor

Casos comuns:

• páginas de catálogo
• listagens paginadas por URL
• páginas institucionais
• blogs
• páginas públicas

Exemplo:

const products = await fetch("/api/products", {
  next: { revalidate: 300 },
}).then(r => r.json());

Benefícios:

• menos JavaScript no client
• melhor performance inicial
• cache automático no servidor
• arquitetura mais simples

---

Quando usar TanStack Query

Use TanStack Query quando os dados:

• Mudam por ação do usuário
• Precisam ser refetchados sem troca de rota
• Dependem de estado local
• Fazem parte de interações ricas

Casos comuns:

• dashboards
• filtros dinâmicos
• paginação client-side
• infinite scroll
• CRUD interativo
• formulários com submit

Exemplo:

const { data, isFetching } = useQuery({
  queryKey: ["products", page, filters],
  queryFn: fetchProducts,
  keepPreviousData: true,
});

Benefícios:

• UX mais fluida
• controle fino de loading e erro
• cache no navegador
• sincronização automática com a UI

---

Uso combinado (padrão recomendado)

O uso combinado deve respeitar responsabilidades diferentes.

Padrão recomendado:

• Server Components + cache do Next.js para leitura
• Client Components + TanStack Query para interação

Exemplo de separação:

• Página de listagem inicial → server
• Filtros, paginação dinâmica → client

Esse modelo evita duplicação de cache e reduz complexidade.

---

Anti-padrões comuns

Evite as seguintes situações:

• usar TanStack Query apenas para cache
• usar hydrate sem necessidade de interação
• usar useQuery em páginas estáticas
• tentar simular estado client com cache do Next.js
• misturar TanStack Query e cache do Next para o mesmo dado

Esses padrões aumentam complexidade sem ganho real.

---

Critério prático de decisão

Situação	Ferramenta adequada
SEO importa	Next.js cache
URL muda	Next.js cache
Leitura simples	Next.js cache
Dados públicos	Next.js cache
Filtros dinâmicos	TanStack Query
Infinite scroll	TanStack Query
Dashboard	TanStack Query
CRUD interativo	TanStack Query

---