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.
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-queryUm 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.
Leia também
- Server-Sent Events vs WebSocket: quando uma via basta17 de novembro de 2026 · 4 min
- Claude Code com Photocraft e Filmcraft: edição grátis15 de novembro de 2026 · 5 min
- Memoização no React: quando useMemo ajuda15 de novembro de 2026 · 4 min
- Paginação: offset vs cursor em listas grandes9 de novembro de 2026 · 4 min