Cinquenta componentes montados com o mesmo endpoint disparam cinquenta chamadas iguais e cada um guarda seu próprio copinho de loading. TanStack Query transforma busca de dados em cache compartilhado com regra explícita: chave define identidade, tempo define frescor, mutação define invalidação. Kent C. Dodds, no artigo Application State Management (kentcdodds.com, 2018), separa estado de servidor de estado de cliente; a library assume o primeiro.

A chave como contrato

queryKey: ['todos', userId] declara a identidade do dado. Duas telas com a mesma chave leem o mesmo cache. Muda parâmetro, muda chave, e o cache reserva espaço novo. staleTime define por quanto tempo o dado vale sem refetch; gcTime define quanto tempo o cache sem uso fica na memória. A documentação do TanStack Query (2025) trata a serialização determinística da chave como parte do contrato: mesmo objeto, mesma ordem de propriedades, mesma chave.

Dedupe na montagem

Três instâncias montadas juntas com a mesma chave executam uma chamada de rede: a library deduplica requisição em voo. Refetch no foco da janela roda por padrão e evita dado velho em aba que ficou aberta. Modo suspense entrega Suspense do React no lugar do hook de loading; a promise do query propaga até o boundary mais próximo.

Mutação e invalidação

useMutation recebe onSuccess que chama invalidateQueries com o prefixo da lista afetada. Update otimista escreve no cache antes da resposta e devolve o estado antigo quando a chamada falha. Duas telas que dependem do mesmo dado invalidam juntas; await queryClient.invalidateQueries segura o toast até o refetch terminar. Mutação que só muda um item do cache por igualdade usa setQueryData no lugar de refetch completo.

Estado global entra onde?

Estado de servidor mora no query cache. Tema, drawer aberto e filtros de UI moram em zustand ou contexto. Token de sessão vive em cookie httpOnly, fora do cache serializado. prefetchQuery no hover do link aquece o cache antes da navegação; queryClient.getQueryData lê dado cacheado no loader. A fronteira entre as duas categorias vira regra de time: quem coloca dado remoto em contexto global reimplementa metade da library, com bug de concorrência incluso.