React Query vs Cache do Next.js: O que se perde no client-side
Por trás do React Query, decisões técnicas podem comprometer todo seu sistema de cache no Next.js. Descubra o que você realmente perde e como evitar armadilhas de performance.
Por que isso é importante
React Query no Next client: fonte da verdade — flicker costuma ser boundary errada.
Leitura relacionada: Curso Next.js · Curso React · shadcn tutorial · Cursos CrazyStack.
Você está sabotando seu cache sem saber
Ao fazer requisições somente do lado do cliente usando React Query, você ignora o potente mecanismo de cache do Next.js. Isso significa: nada do revalidate, tags ou controle granular. O ganho de UX é real, mas o custo de performance pode surpreender.
Atenção
O cache HTTP criado pelo navegador NÃO substitui o cache inteligente do Next. São níveis e propósitos diferentes!
O que você perde de verdade
Requests feitas por React Query no cliente NÃO passam pelo pipeline de cache do Next.js. Você perde:
- Cache persistente de páginas e componentes gerenciado pelo Next - Manipulação de tags e revalidação automática (ISR) - Controle centralizado da validação e refetch dos dados - Otimização global para SEO e respostas instantâneas no primeiro load
Atenção
Cache HTTP do browser depende de headers e expira fácil. Já o Next decide até quando um conteúdo pode ser considerado fresco, mesmo após o reload da página ou deploys.
Quando React Query brilha?
Quando você precisa de atualizações em tempo real, experiências responsivas e atualizações locais rápidas. O valor está no update visual instantâneo.
Atenção
Mesmo nesses casos, a estratégia recomendada é: traga os dados iniciais via Server Components (ou server-side functions), aproveite o cache do Next E só depois hidrate o React Query.
Como unir o melhor dos mundos
Carregue os dados do primeiro render no server. Use React Query para consumir o “pré-cache” inicial, garantindo performance, instantaneidade e atualização sem perder o controle de caching do Next.
Experiência real para devs frontend
Quem mistura server-first para os dados iniciais + React Query com hydration já entrega o loading mais rápido possível e traz ganhos para UX, caching, SEO e até manutenção.
Como implementar na prática
Faça o fetch dos dados principais server-side (em Server Components ou getServerSideProps) e injete esses dados como estado inicial no React Query. O usuário vê os dados imediatamente e React Query mantém tudo reativo depois.
Erro comum
Não inverta: se buscar tudo só com React Query direto do browser, seu app perde controle das regras de cache do Next e pode ficar lento para o próximo usuário.
Tags, revalidate e o poder do Next.js
Server-side caching permite usar tags personalizadas, escolher revalidate por rota/dados, cache inteligente até para APIs externas e devolver páginas frescas sem ghost data.
Impacto em SEO e escala
Dados pré-hidratados no server garantem conteúdo para crawlers, melhores métricas no Core Web Vitals e respostas rápidas, até em picos e deploys.
Dica técnica
Você pode usar o método dehydrate do React Query aliado ao rendering server-first, garantindo que toda árvore cacheada seja entregue pronta para o usuário - e só depois as atualizações client-side entram em ação!
Nunca abra mão dos fundamentos
O segredo não é só performance - é ter controle. Use React Query para UX e Next para caching. Sabendo mesclar, ninguém segura seu app.
Explore mais no Youtube
Quer ver isso tudo em prática? Confira vídeos práticos e exemplos reais no canal Dev Doido no Youtube: youtube.com/@DevDoido
Checklist rápido: nunca esqueça
- Dados do primeiro load sempre via Server Components - Inicialize React Query com state já preenchido - Cache do browser é apenas um extra, não baseie seu app só nele - Otimize cada camada: server, client e browser devem se complementar
Perguntas frequentes
Erro oculto React Query no client Next?
Hidratação/cache desalinhados e fetch duplicado. Desenhe a fonte da verdade.
Sintoma?
Flicker e dados velhos.
Fix?
Boundaries e invalidação explícita.
RSC?
Reduz a necessidade em vários casos.
Continue explorando
Continue: Curso Next.js · Curso React · shadcn tutorial · Cursos CrazyStack.
Perguntas frequentes
Erro oculto React Query no client Next?
Hidratação/cache desalinhados e fetch duplicado. Desenhe a fonte da verdade.
Sintoma?
Flicker e dados velhos.
Fix?
Boundaries e invalidação explícita.
RSC?
Reduz a necessidade em vários casos.
O que você perde de verdade
Requests feitas por React Query no cliente NÃO passam pelo pipeline de cache do Next.js. Você perde: - Cache persistente de páginas e componentes gerenciado pelo Next - Manipulação de tags e revalidação automática (ISR) - Controle centralizado da validação e refetch dos dados - Otimização global para SEO e respostas instantâneas no primeiro load
Quando React Query brilha?
Quando você precisa de atualizações em tempo real, experiências responsivas e atualizações locais rápidas. O valor está no update visual instantâneo.
Como unir o melhor dos mundos
Carregue os dados do primeiro render no server. Use React Query para consumir o “pré-cache” inicial, garantindo performance, instantaneidade e atualização sem perder o controle de caching do Next.
Como implementar na prática
Faça o fetch dos dados principais server-side (em Server Components ou getServerSideProps) e injete esses dados como estado inicial no React Query. O usuário vê os dados imediatamente e React Query mantém tudo reativo depois.