deckardger/tanstack-integration-best-practices

O que tanstack-integration-best-practices faz?

Melhores práticas para integrar TanStack Query com TanStack Router e TanStack Start. Padrões para fluxo de dados full-stack, SSR e coordenação de cache.

Visão Geral

Este guia cobre padrões essenciais para integrar perfeitamente TanStack Query, TanStack Router e TanStack Start. Você aprenderá como coordenar cache, lidar com SSR e gerenciar fluxo de dados full-stack sem inconsistências.

Principais Conceitos

• Coordenação de Cache: Sincronize dados entre Query e Router para evitar chamadas de rede duplicadas e dados obsoletos.
• Fluxo de Dados SSR: Estratégias para pré-carregar dados no servidor e hidratá-los corretamente no cliente.
• Integração de Roteamento: Use TanStack Router para gerenciar estado de navegação e gatilhos de busca.

Padrões Recomendados

1. Data Prefetching no Servidor: Utilize @tanstack/react-query com streaming ou defer no Start.

   import { queryClient } from '~/lib/queryClient';
   import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
   

2. Estado de Rota: Associe parâmetros de URL a consultas Query.

   import { useMatch } from '@tanstack/react-router';
   import { useQuery } from '@tanstack/react-query';
   const { params } = useMatch('/projects/$id');
   const { data } = useQuery({
     queryKey: ['project', params.id],
     queryFn: () => fetchProject(params.id),
   });
   

3. Atualização Otimista: Combine mutações Query com navegação Router.

   const navigate = useNavigate();
   const mutation = useMutation({
     mutationFn: updateProject,
     onSuccess: (data) => {
       queryClient.invalidateQueries({ queryKey: ['project'] });
       navigate({ to: '/projects/$id', params: { id: data.id } });
     },
   });
   

Boas Práticas

• Sempre defina staleTime apropriado para evitar refetch desnecessário.
• Use loader no Router para pré-carregar dados da Query.
• Evite duplicação de estado: confie no cache da Query como fonte única da verdade.

Links Úteis

• Documentação TanStack Query
• Documentação TanStack Router
• TanStack Start