TanStack Query: pare de buscar dados com useEffect

Veja os problemas de buscar dados com useEffect e useState, e como o TanStack Query resolve cache, loading, erro, refetch e invalidação com poucas linhas, além de quando ele não é necessário.

tecnico react frontend 5 min de leitura

Buscar dados de uma API em React parece simples: um useEffect, um fetch e um useState. Funciona na primeira tela. Depois vêm o loading, o erro, o cache, a atualização após uma mutação, e o que era um trecho de cinco linhas vira um emaranhado repetido em cada componente.

O jeito tradicional e onde ele quebra

function Usuarios() {
  const [usuarios, setUsuarios] = useState([]);
  const [carregando, setCarregando] = useState(true);
  const [erro, setErro] = useState(null);
 
  useEffect(() => {
    fetch("/api/usuarios")
      .then((res) => res.json())
      .then(setUsuarios)
      .catch(setErro)
      .finally(() => setCarregando(false));
  }, []);
 
  if (carregando) return <p>Carregando...</p>;
  if (erro) return <p>Erro ao carregar</p>;
  return <ul>{usuarios.map((u) => <li key={u.id}>{u.nome}</li>)}</ul>;
}

Esse código tem problemas escondidos:

  • Sem cache. Sair da tela e voltar refaz a requisição, mostrando loading de novo.
  • Duplicação. Dois componentes que precisam dos mesmos dados disparam duas requisições.
  • Condição de corrida. Se o parâmetro muda rápido, uma resposta antiga pode chegar depois da nova e sobrescrevê-la.
  • Sem atualização. Os dados ficam velhos se o usuário volta à aba depois de uma hora.
  • Muito código repetido. Cada tela refaz a mesma estrutura de três estados.

A ideia: dados do servidor não são estado local

O TanStack Query parte de uma observação: os dados que vêm do servidor são um cache de algo que pertence a outro lugar, e podem ficar desatualizados a qualquer momento. Tratar isso como useState comum é o que gera a bagunça. A biblioteca assume o gerenciamento desse cache pra você.

Primeiros passos

npm install @tanstack/react-query

Um provider na raiz da aplicação:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
const queryClient = new QueryClient();
 
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Usuarios />
    </QueryClientProvider>
  );
}

E o mesmo componente de antes:

import { useQuery } from "@tanstack/react-query";
 
function Usuarios() {
  const { data, isPending, error } = useQuery({
    queryKey: ["usuarios"],
    queryFn: () => fetch("/api/usuarios").then((res) => res.json()),
  });
 
  if (isPending) return <p>Carregando...</p>;
  if (error) return <p>Erro ao carregar</p>;
  return <ul>{data.map((u) => <li key={u.id}>{u.nome}</li>)}</ul>;
}

Sem useEffect, sem três estados manuais. E ganhou de graça tudo que faltava.

A queryKey é a chave de tudo

O queryKey identifica os dados no cache. Dois componentes que usam a mesma chave compartilham o resultado, com uma única requisição. Parâmetros entram na chave, e uma mudança neles dispara a busca certa:

const { data } = useQuery({
  queryKey: ["usuario", id],
  queryFn: () => fetch(`/api/usuarios/${id}`).then((res) => res.json()),
});

Quando o id muda, a chave muda, e a biblioteca busca o novo usuário. O problema da condição de corrida some, porque cada chave tem seu próprio resultado.

Cache e dados "velhos"

Dois conceitos importantes:

  • staleTime: por quanto tempo os dados são considerados frescos. Dentro desse prazo, nenhuma nova requisição acontece.
  • Revalidação em segundo plano: depois que os dados ficam velhos, ao voltar à tela a biblioteca mostra o cache na hora e atualiza por baixo, sem loading.
useQuery({
  queryKey: ["usuarios"],
  queryFn: buscarUsuarios,
  staleTime: 60 * 1000, // frescos por 1 minuto
});

É a mesma ideia de stale-while-revalidate que aparece em cache de HTTP e no ISR do Next.js: mostrar algo rápido e corrigir em seguida.

Mutações e invalidação

Alterar dados é com useMutation. Depois de uma alteração bem-sucedida, você invalida a chave, e as telas que usam esses dados buscam de novo sozinhas:

import { useMutation, useQueryClient } from "@tanstack/react-query";
 
function NovoUsuario() {
  const queryClient = useQueryClient();
 
  const criar = useMutation({
    mutationFn: (dados) =>
      fetch("/api/usuarios", {
        method: "POST",
        body: JSON.stringify(dados),
      }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["usuarios"] });
    },
  });
 
  return (
    <button onClick={() => criar.mutate({ nome: "Ana" })}>
      {criar.isPending ? "Salvando..." : "Criar"}
    </button>
  );
}

A lista de usuários se atualiza sem você passar o novo item manualmente por props ou contexto.

O que mais vem junto

  • Retry automático em caso de falha de rede.
  • Refetch ao voltar o foco para a janela ou ao reconectar.
  • Paginação e scroll infinito com useInfiniteQuery.
  • Atualizações otimistas, mostrando o resultado antes da confirmação do servidor.
  • DevTools pra inspecionar o cache.

Quando você não precisa dele

Com Next.js e Server Components, boa parte da busca inicial de dados acontece no servidor, sem useEffect nem biblioteca de cache no cliente. O TanStack Query continua valendo pra partes interativas: listas que atualizam, filtros, mutações com feedback imediato, dados que mudam durante a sessão. Em um site simples, com poucas chamadas e dados quase estáticos, um fetch direto é suficiente.

Fechando

O useEffect serve pra sincronizar com o mundo externo, e buscar dados com ele funciona, mas cobra caro em cada detalhe que você precisa reimplementar. O TanStack Query trata dados do servidor como o que eles são, um cache que precisa de invalidação e revalidação, e tira de você o código repetitivo que mais costuma ter bug.

Direto na sua
caixa de entrada.

Um aviso por e-mail sempre que eu publicar um post novo. Sem spam, sem newsletter chata, só isso.