TanStack Query no React: guia para cache de dados

O TanStack Query (antigo React Query) é uma biblioteca que gerencia o "estado do servidor" no React: busca dados, guarda em cache, revalida em segundo plano e controla loading e erros sem que você escreva tudo isso à mão. Se o seu app faz várias chamadas a uma API ou ao Supabase, usar o TanStack Query no React reduz código repetido e deixa a interface mais rápida e previsível.

##O que é o TanStack Query e que problema ele resolve

Sem uma biblioteca dedicada, o padrão comum é combinar useEffect, useState e flags de loading. Isso funciona em telas simples, mas cresce mal: você precisa tratar race conditions, evitar requisições duplicadas, atualizar a tela após uma mutação e lidar com erros.

O TanStack Query trata esses pontos por padrão:

• Cache automático por chave de consulta (queryKey)
• Deduplicação de requisições iguais feitas ao mesmo tempo
• Revalidação quando a janela volta ao foco ou a conexão retorna
• Retentativas automáticas em caso de falha
• Estados prontos para uso: carregando, erro, sucesso

A versão 5, anunciada oficialmente pelo time do TanStack em 2023, é a base atual da biblioteca e trouxe uma API mais enxuta, com um único formato de objeto para os hooks principais.

##Como configurar o TanStack Query no React com Vite

A instalação é simples. Em um projeto React com Vite, rode npm install @tanstack/react-query e envolva a aplicação com o provider:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Rotas />
    </QueryClientProvider>
  )
}

Depois, uma consulta usa o hook useQuery. Exemplo buscando posts no Supabase:

import { useQuery } from '@tanstack/react-query'
import { supabase } from './supabase'

function usePosts() {
  return useQuery({
    queryKey: ['posts'],
    queryFn: async () => {
      const { data, error } = await supabase
        .from('posts')
        .select('*')
        .eq('status', 'published')
      if (error) throw error
      return data
    },
  })
}

Note que a função de busca precisa lançar o erro (throw) para o TanStack Query reconhecer a falha. Esse é um detalhe muito comum ao integrar com o Supabase.

##Cache de dados: staleTime e gcTime

Entender esses dois conceitos evita a maioria das dúvidas sobre cache:

• staleTime: por quanto tempo o dado é considerado "fresco". O padrão é 0, ou seja, o dado é tratado como desatualizado logo após ser buscado e pode ser revalidado em novas montagens do componente.
• gcTime (antigo cacheTime): por quanto tempo um dado sem uso fica na memória antes de ser descartado. O padrão é de 5 minutos. Na v5, o nome mudou de cacheTime para gcTime.

Para dados que mudam pouco, como categorias ou configurações, aumente o staleTime (por exemplo, 5 minutos) e evite requisições desnecessárias. Para dados sensíveis a mudanças, como estoque ou saldo, mantenha o padrão.

##Mutations e atualização da interface

Para criar, editar ou excluir dados, use useMutation. Depois de salvar, invalide a consulta relacionada para que a lista seja atualizada:

const mutation = useMutation({
  mutationFn: criarPost,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['posts'] })
  },
})

Para uma experiência mais fluida, é possível usar atualizações otimistas: a interface muda na hora e volta ao estado anterior se a requisição falhar.

##Quando usar (e quando não usar) o TanStack Query

Vale usar quando o app depende de dados vindos de API, precisa de cache, tem listas, paginação ou várias telas consumindo os mesmos dados.

Pode ser desnecessário em uma landing page estática, em um site com poucos dados fixos ou quando o framework já cuida da busca no servidor. Além disso, ele não substitui estado de interface, como abrir um modal ou guardar o tema escolhido. Para isso, useState, Context ou uma biblioteca leve continuam adequados.

##Perguntas Frequentes

O TanStack Query substitui o Redux? Não totalmente. Ele substitui o Redux no gerenciamento de dados que vêm do servidor. Para estado de interface e regras locais, você ainda pode usar useState, Context ou outra biblioteca.

TanStack Query e React Query são a mesma coisa? Sim. React Query é o nome antigo. Hoje o projeto se chama TanStack Query e tem adaptadores para React, Vue, Solid, Svelte e Angular.

Posso usar TanStack Query com Supabase? Pode. Basta colocar a chamada do Supabase dentro do queryFn e lançar o erro retornado, para que a biblioteca cuide do cache, das retentativas e da revalidação.

Qual a diferença entre staleTime e gcTime? O staleTime define quando o dado deixa de ser considerado fresco. O gcTime define quando um dado sem uso é removido da memória.

TanStack Query funciona em sites pequenos? Funciona, mas só compensa quando há chamadas de dados relevantes. Em sites com conteúdo estático, o benefício é pequeno.

##Conclusão

Usar o TanStack Query no React é uma das formas mais eficientes de organizar dados vindos do servidor: menos código, menos requisições e telas mais responsivas. Comece por uma consulta simples, ajuste o staleTime conforme a natureza do dado e invalide o cache após cada mutation. Na Stormcore, aplicamos esse tipo de prática na criação de sites e sistemas com React, Vite e Supabase, buscando performance e facilidade de manutenção.