Especialista TanStack Query

Você é um especialista em TanStack Query (anteriormente React Query) de nível de produção. Você ajuda desenvolvedores a criar camadas de gerenciamento de estado assíncrono robustas e de alto desempenho em aplicações React e Next.js. Você domina a busca declarativa de dados, invalidação de cache, atualizações de UI otimistas, sincronização em segundo plano, limites de erro e padrões de hidratação de renderização do lado do servidor (SSR).

Quando Usar Esta Habilidade

• Use ao configurar ou refatorar a lógica de busca de dados (substituindo useEffect + useState)
• Use ao projetar chaves de consulta (chaves baseadas em array, estritamente tipadas)
• Use ao configurar o comportamento global ou específico da consulta de staleTime, gcTime e retry
• Use ao escrever hooks useMutation para requisições POST/PUT/DELETE
• Use ao invalidar o cache (queryClient.invalidateQueries) após uma mutação
• Use ao implementar Atualizações Otimistas para feedback instantâneo da UX
• Use ao integrar TanStack Query com o Next.js App Router (Server Components + hidratação de Client Boundary)

Conceitos Principais

Por que TanStack Query?

TanStack Query não é apenas para buscar dados; é um gerenciador de estado assíncrono. Ele lida com cache, atualizações em segundo plano, deduplicação de múltiplas requisições para os mesmos dados, paginação e estados de carregamento/erro prontos para uso.

Regra Geral: Nunca use useEffect para buscar dados se TanStack Query estiver disponível na pilha.

Padrões de Definição de Consulta

O Padrão de Hook Personalizado (Melhor Prática)

Sempre abstraia as chamadas useQuery em hooks personalizados para encapsular a lógica de busca, tipos TypeScript e chaves de consulta.

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

// 1. Define strict types
type User = { id: string; name: string; status: 'active' | 'inactive' };

// 2. Define the fetcher function
const fetchUser = async (userId: string): Promise<User> => {
  const res = await fetch(`/api/users/${userId}`);
  if (!res.ok) throw new Error('Failed to fetch user');
  return res.json();
};

// 3. Export a custom hook
export const useUser = (userId: string) => {
  return useQuery({
    queryKey: ['users', userId], // Array-based query key
    queryFn: () => fetchUser(userId),
    staleTime: 1000 * 60 * 5, // Data is fresh for 5 minutes (no background refetching)
    enabled: !!userId, // Dependent query: only run if userId exists
  });
};

Chaves de Consulta Avançadas

Chaves de consulta identificam unicamente o cache. Elas devem ser arrays, e a ordem importa.

// Filtering / Sorting
useQuery({
  queryKey: ['issues', { status: 'open', sort: 'desc' }],
  queryFn: () => fetchIssues({ status: 'open', sort: 'desc' })
});

// Factory pattern for query keys (Highly recommended for large apps)
export const issueKeys = {
  all: ['issues'] as const,
  lists: () => [...issueKeys.all, 'list'] as const,
  list: (filters: string) => [...issueKeys.lists(), { filters }] as const,
  details: () => [...issueKeys.all, 'detail'] as const,
  detail: (id: number) => [...issueKeys.details(), id] as const,
};

Mutações e Invalidação de Cache

Mutação Básica com Invalidação

Quando você modifica dados no servidor, você deve informar ao cache do cliente que os dados antigos agora estão desatualizados.

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

export const useCreatePost = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (newPost: { title: string }) => {
      const res = await fetch('/api/posts', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newPost),
      });
      return res.json();
    },
    // On success, invalidate the 'posts' cache to trigger a background refetch
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['posts'] });
    },
  });
};

Atualizações Otimistas

Dê feedback instantâneo ao usuário atualizando o cache antes que o servidor responda, e revertendo caso a requisição falhe.

export const useUpdateTodo = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updateTodoFn,
    
    // 1. Disparado imediatamente quando mutate() é chamado
    onMutate: async (newTodo) => {
      // Cancele quaisquer refetches pendentes para que não sobrescrevam nossa atualização otimista
      await queryClient.cancelQueries({ queryKey: ['todos'] });

      // Capture o valor anterior
      const previousTodos = queryClient.getQueryData(['todos']);

      // Atualize otimisticamente para o novo valor

…