Data Fetching

React Query Essencial

TanStack Query (React Query)

Domine cache, mutations, otimização e boas práticas para gerenciar estado assíncrono de forma profissional.

Este guia assume conhecimento básico de React e hooks. Foco em uso prático e real.

Setup Inicial

Configuração básica

Instale o React Query e configure o QueryClient no root da sua aplicação.

terminal

npm install @tanstack/react-query
# ou
pnpm add @tanstack/react-query

app/layout.tsx

'use client';
 
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState } from 'react';
 
export default function RootLayout({ children }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // 1 minuto
        retry: 1,
      },
    },
  }));
 
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

useQuery — Buscar Dados

GET requests

Cache Automático

Dados são cacheados e reutilizados automaticamente

Refetch Inteligente

Atualiza dados quando necessário (window focus)

Loading States

Estados de loading, error e success prontos

Retry Automático

Tenta novamente em caso de falha

components/user-profile.tsx

import { useQuery } from '@tanstack/react-query';
 
async function fetchUser(id: string) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error('Failed to fetch');
  return res.json();
}
 
export function UserProfile({ userId }: { userId: string }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
 
  if (isLoading) return <div>Carregando...</div>;
  if (error) return <div>Erro: {error.message}</div>;
 
  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}

useMutation — Modificar Dados

POST, PUT, DELETE

Use mutations para criar, atualizar ou deletar dados. Invalide o cache automaticamente após sucesso.

components/create-user-form.tsx

import { useMutation, useQueryClient } from '@tanstack/react-query';
 
async function createUser(data: { name: string; email: string }) {
  const res = await fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(data),
  });
  if (!res.ok) throw new Error('Failed to create');
  return res.json();
}
 
export function CreateUserForm() {
  const queryClient = useQueryClient();
 
  const mutation = useMutation({
    mutationFn: createUser,
    onSuccess: () => {
      // Invalida e refetch da lista de usuários
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
 
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    mutation.mutate({
      name: formData.get('name') as string,
      email: formData.get('email') as string,
    });
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <input name="name" required />
      <input name="email" type="email" required />
      <button disabled={mutation.isPending}>
        {mutation.isPending ? 'Criando...' : 'Criar'}
      </button>
      {mutation.isError && <p>Erro: {mutation.error.message}</p>}
    </form>
  );
}

Boas Práticas

Dicas essenciais

Use Query Keys Consistentes

Sempre use arrays: ['users', userId] ao invés de strings simples

Configure staleTime

Defina quanto tempo os dados são considerados 'frescos'

Invalide com Precisão

Use invalidateQueries com queryKey específica, não tudo

Otimistic Updates

Atualize UI antes da resposta do servidor para melhor UX

Error Boundaries

Sempre trate erros com error boundaries ou try/catch

Recursos Oficiais

Documentação e ferramentas

Documentação Oficial

Guia completo do TanStack Query

DevTools

Ferramenta de debug para React Query

Exemplos

Exemplos práticos e casos de uso

Pronto para otimizar seu data fetching?

Explore mais guias e ferramentas práticas para devs.

Voltar às Dicas

Conteúdo relacionado

Dicas de IA para DesenvolvedoresGuia prático de ferramentas IA, uso consciente de tokens e modelos: v0, Copilot, prompt engineering, boas práticas e ferramentas para produtividade dev.

Tailwind CSS + shadcn/ui — Guia PráticoSetup completo, componentes reutilizáveis, padrões de código e boas práticas com Tailwind CSS e shadcn/ui para projetos React e Next.js.

Recursos para Desenvolvedores — Jr, Pleno e SeniorSnippets, comparações before/after, padrões de código e playground interativo filtrado por nível: junior, pleno e senior.

10 min de leitura

'use client';

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

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

import { useState } from 'react';

export default function RootLayout({ children }) {

const [queryClient] = useState(() => new QueryClient({

defaultOptions: {

queries: {

staleTime: 60 * 1000, // 1 minuto

retry: 1,

}));

return (

{children}

</QueryClientProvider>

);

}

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

async function fetchUser(id: string) {

const res = await fetch(`/api/users/${id}`);

if (!res.ok) throw new Error('Failed to fetch');

return res.json();

}

export function UserProfile({ userId }: { userId: string }) {

const { data, isLoading, error } = useQuery({

queryKey: ['user', userId],

queryFn: () => fetchUser(userId),

});

if (isLoading) return <div>Carregando...</div>;

if (error) return <div>Erro: {error.message}</div>;

return (

<div>

<p>{data.email}</p>

</div>

);

}

import { useMutation, useQueryClient } from '@tanstack/react-query';

async function createUser(data: { name: string; email: string }) {

const res = await fetch('/api/users', {

method: 'POST',

body: JSON.stringify(data),

});

if (!res.ok) throw new Error('Failed to create');

return res.json();

}

export function CreateUserForm() {

const queryClient = useQueryClient();

const mutation = useMutation({

mutationFn: createUser,

onSuccess: () => {

// Invalida e refetch da lista de usuários

queryClient.invalidateQueries({ queryKey: ['users'] });

});

const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {

e.preventDefault();

const formData = new FormData(e.currentTarget);

mutation.mutate({

name: formData.get('name') as string,

email: formData.get('email') as string,

});

};

return (

{mutation.isPending ? 'Criando...' : 'Criar'}

</button>

{mutation.isError && <p>Erro: {mutation.error.message}</p>}

</form>

);

}