Um Guia de Campo para o Ecossistema TanStack

O TanStack é uma coleção de bibliotecas headless, type-safe e composáveis que lidam com busca de dados, roteamento, tabelas, formulários, virtualização e estado do cliente. O ecossistema surgiu do React Query, posteriormente renomeado para TanStack Query. Suas bibliotecas de dados e UI disponibilizam adaptadores para React, Vue, Solid, Svelte e Angular, enquanto seu roteador e framework full-stack têm como alvo React e Solid. O TanStack não é, em si, um framework; o projeto descreve seus componentes como utilitários headless e composáveis, e apenas um deles — o TanStack Start — é um framework full-stack.

Se você já usa o TanStack Query e continua vendo menções ao Router, Start, Table, Form, Store, DB e AI, o problema prático é descobrir o que cada um faz, qual é o seu grau de maturidade e quando utilizá-lo no lugar da stack padrão do React (Next.js, React Router, Redux/Zustand, React Hook Form, Apollo, AG Grid). Este guia mapeia o ecossistema biblioteca por biblioteca, apresenta uma assinatura mínima de código para cada uma, indica o nível de maturidade com um número de versão e mostra como as peças se conectam. É um mapa, não um tutorial — os passos de configuração estão na documentação oficial, com links ao longo do texto.

O Que É o TanStack e Por Que “Headless” Importa

O TanStack é um conjunto de bibliotecas independentes que compartilham uma única regra de design: a biblioteca é responsável pela lógica, e você é responsável pela renderização. Toda biblioteca TanStack separa estado de marcação — a biblioteca executa a máquina de estados; o seu componente decide como a interface deve parecer. É isso que “headless” significa na prática: não há CSS do TanStack para sobrescrever, nenhum componente do TanStack para estender e nenhuma opinião do fornecedor sobre como sua UI deve se apresentar. O TanStack Query é o ponto de origem da marca — foi renomeado de React Query quando o ecossistema cresceu — embora o TanStack Table seja anterior à mudança de nome, portanto o Query é a origem popularizadora, não literalmente a primeira biblioteca.

A filosofia compartilhada é frequentemente resumida como “seja dono do seu código, não do seu framework.” Três propriedades decorrem dela:

• Headless: lógica sem UI. Você conecta o estado da biblioteca a qualquer marcação, sistema de design ou camada de acessibilidade que já utiliza.
• Core agnóstico de framework: as bibliotecas de dados e UI — Query, Table, Form, Virtual e Store — disponibilizam adaptadores oficiais para React, Vue, Solid, Svelte e Angular. O roteamento é a exceção: o TanStack Router e o TanStack Start têm como alvo apenas React e Solid.
• Composabilidade em vez de monolitos: cada biblioteca funciona sozinha ou em conjunto. Você adota o Query sem adotar o Router, ou o Table sem adotar o Start.

O Mapa Biblioteca por Biblioteca

Cada biblioteca abaixo cobre o que faz, o que substitui, sua maturidade em junho de 2026 e uma assinatura mínima de código. As assinaturas representam a superfície da API, não um tutorial de configuração — siga os links para a documentação oficial para instalar e configurar.

TanStack Query — estado do servidor

O TanStack Query gerencia o estado assíncrono do servidor: busca de dados, cache, refetch em segundo plano, deduplicação e atualizações otimistas. Ele substitui o padrão manual de fetch combinado com useEffect, com o qual a maioria dos aplicativos React começou. É estável.

// @tanstack/react-query v5.101.0
const { data: users, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then((res) => res.json()),
});

O Query é o ponto de entrada mais amplamente adotado no ecossistema e a mudança com maior retorno sobre investimento em uma base de código React existente, pois elimina os estados de carregamento e erro escritos manualmente sem tocar nas camadas de roteamento ou UI.

TanStack Router — roteamento type-safe

O TanStack Router é um roteador client-side completamente type-safe para React e Solid. Caminhos de rota, parâmetros de URL, parâmetros de busca, contexto de rota e dados de loader são todos tipados de ponta a ponta, de modo que o compilador — e não o usuário em tempo de execução — detecta um link com formato de parâmetro incorreto. Ele substitui o React Router para SPAs e é estável.

// @tanstack/react-router v1.170.16
const Route = createFileRoute('/products')({
  validateSearch: (search) => ({
    category: (search.category as string) ?? 'all',
    page: Number(search.page ?? 1),
  }),
});

const { category, page } = Route.useSearch();

O Router trata os parâmetros de busca da URL como estado tipado e validado, o que torna filtros, ordem de classificação e paginação compartilháveis via URL e restauráveis ao recarregar a página. Isso resolve uma classe específica e reproduzível de bugs: replays de sessão em dashboards SPA frequentemente revelam usuários perdendo estado de filtro, classificação e paginação ao recarregar a página ou navegar para trás, quando esse estado estava na memória do componente em vez de na URL — exatamente o modo de falha que os parâmetros de busca tipados eliminam.

TanStack Table — data grids headless

O TanStack Table lida com a lógica de data grids — definições de colunas, ordenação, filtragem, paginação, seleção de linhas, agrupamento e visibilidade de colunas — deixando cada pixel da UI para você. Ele estabeleceu o padrão headless no ecossistema React e substitui bibliotecas de grid opinativas como AG Grid e MUI DataGrid para equipes que desejam controle total da marcação. É estável, com uma linha V9 em desenvolvimento que ainda não é o latest publicado.

// @tanstack/react-table v8.21.3
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
});

A instância do Table gerencia o estado; sua marcação renderiza o que esse estado descreve. Combinado com o Query para paginação e filtragem no lado do servidor, ele lida com grandes conjuntos de dados sem carregar tudo no cliente.

TanStack Form — formulários tipados

O TanStack Form gerencia o estado de formulários e validação — erros no nível de campo e de formulário, validação síncrona e assíncrona, estado de envio — sem renderizar nada por conta própria. É o sucessor headless do React Hook Form e é estável (v1).

// @tanstack/react-form v1.33.0
const form = useForm({
  defaultValues: { email: '', password: '' },
  onSubmit: async ({ value }) => { await loginUser(value); },
});

Valores de campo, schemas de validação e payloads de envio são tipados de ponta a ponta, e a validação assíncrona (verificar disponibilidade de nome de usuário, por exemplo) é um recurso de primeira classe com debouncing e cancelamento gerenciados pela biblioteca.

TanStack Virtual — virtualização de listas e grids

O TanStack Virtual renderiza apenas as linhas ou colunas atualmente visíveis na viewport para listas e grids roláveis de grande porte, mantendo o DOM pequeno enquanto o conjunto de dados permanece enorme. Ele fornece as medidas e os offsets; você renderiza a marcação. Substitui soluções de windowing escritas manualmente e bibliotecas como react-window e react-virtualized. É estável.

// @tanstack/react-virtual v3.14.3
const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 48,
});

const rows = virtualizer.getVirtualItems();

useVirtualizer retorna os itens virtuais em exibição mais o tamanho total; você posiciona cada item de forma absoluta pelo seu offset. Combina naturalmente com o Table para grandes data grids — o Table gerencia o modelo de linhas, o Virtual mantém apenas as linhas visíveis no DOM — de modo que uma lista de cinco mil linhas rola em velocidade total.

TanStack Store — estado do cliente

O TanStack Store é um store reativo de granularidade fina que alimenta os internos de várias outras bibliotecas TanStack e é disponibilizado como um pacote independente. Oferece uma alternativa ao Zustand e ao Redux para estado do cliente (não do servidor). Como pacote independente, está em alpha (v0.11.0), portanto trate com cautela qualquer enquadramento do tipo “substitui Zustand/Redux” levando em conta essa maturidade.

// @tanstack/store v0.11.0 + @tanstack/react-store
import { Store } from '@tanstack/store';
import { useStore } from '@tanstack/react-store';

const countStore = new Store(0);
// em um componente:
const count = useStore(countStore);

A divisão de responsabilidades é o modelo mental útil: o Query gerencia o estado do servidor, o Store gerencia o estado do cliente. Para a maioria dos aplicativos, Query combinado com uma pequena quantidade de Store (ou sua ferramenta de estado do cliente existente) cobre toda a superfície de estado.

TanStack Start — framework full-stack

O TanStack Start é um framework React full-stack construído sobre o TanStack Router. Ele traz roteamento baseado em arquivos, server functions, SSR com streaming e TypeScript de ponta a ponta, mantendo os mecanismos subjacentes visíveis. Posiciona-se como alternativa ao Next.js e ao Remix. O Start está no estágio de Release Candidate (linha de release atual 1.168.x), ainda não declarado estável, e seu suporte a React Server Components está disponível de forma experimental, e não como padrão de produção.

// @tanstack/react-start v1.168.26
import { createServerFn } from '@tanstack/react-start';

const getUser = createServerFn({ method: 'GET' })
  .validator((userId: string) => userId)
  .handler(async ({ data: userId }) => db.users.findById(userId));

As server functions são funções tipadas e co-localizadas que executam no servidor, mas podem ser chamadas a partir de componentes cliente como qualquer função assíncrona — os tipos fluem da fonte de dados até o componente sem anotação manual, e não há uma camada de API separada para manter em buscas simples. Observe que o caminho de importação é @tanstack/react-start; guias mais antigos que mostram @tanstack/start estão desatualizados.

TanStack DB — store reativo do cliente

O TanStack DB é um store reativo e client-first com coleções, live queries e mutações otimistas. Você define coleções, escreve queries contra elas, e qualquer componente que observa uma query é re-renderizado quando os dados subjacentes mudam — seja por uma sincronização com o servidor, uma mutação local ou uma atualização otimista. Ele fica na frente do seu próprio backend ou API; é uma camada de store/sincronização no lado do cliente, não um substituto de backend-as-a-service como Firebase ou Supabase. Está em beta (v0.6.9).

O DB aborda a lacuna além do fetch-and-cache: aplicativos intensivos em dados com atualizações em tempo real, filtragem complexa no lado do cliente e estado multi-usuário. A comparação com “Firebase headless” é uma analogia para o modelo de query reativo, não uma afirmação de substituição de infraestrutura hospedada.

TanStack AI — primitivos de IA agnósticos de provedor

O TanStack AI fornece primitivos headless para funcionalidades baseadas em IA — tratamento de respostas em streaming, estado de conversação e uma interface unificada entre provedores de modelos — sem te prender a um único SDK ou provedor. Está em beta, conforme anunciado no blog do TanStack, não em alpha ou experimental.

Respostas em streaming (tokens chegando de forma incremental) são tratadas nativamente, o que é o que faz interfaces de chat e geração com IA parecerem responsivas. O valor é arquitetural: uma camada agnóstica de provedor mantém você livre para trocar de provedor de modelo sem reescrever o estado da sua UI.

A Tabela de Maturidade

A maturidade varia significativamente ao longo do ecossistema, e o erro mais comum em visões gerais do ecossistema é apresentar bibliotecas experimentais como consolidadas. Cinco das nove bibliotecas cobertas aqui — Query, Router, Table, Form e Virtual — são estáveis em junho de 2026; Start está no estágio de Release Candidate com React Server Components disponíveis de forma experimental; DB e AI estão em beta; e Store está em alpha. A tabela abaixo registra a versão publicada e o status de cada biblioteca.

Consulte os docs vinculados para o status de release atual.

Como as Peças se Encaixam

As bibliotecas são projetadas para compor, e a integração central é o Router fazendo pré-fetch de dados do Query via loaders, de modo que um componente renderiza contra um cache aquecido. Um loader de rota pode chamar queryClient.ensureQueryData antes que o componente seja montado; no momento em que ele renderiza, os dados já estão em cache. Quando o Start adiciona SSR a esse pipeline, os dados são pré-carregados no servidor e desidratados, chegando como HTML totalmente renderizado na primeira requisição.

// @tanstack/react-router v1.170.16 + @tanstack/react-query v5.101.0
const Route = createFileRoute('/users/$userId')({
  loader: ({ params }) =>
    queryClient.ensureQueryData({
      queryKey: ['user', params.userId],
      queryFn: () => fetchUser(params.userId),
    }),
  component: UserPage,
});

Três conexões concretas merecem destaque:

1. Router → Query: loaders de rota fazem pré-fetch de dados do Query, eliminando o flash de carregamento na primeira renderização.
2. Start → Router: o Start é construído sobre o Router, de modo que o modelo de roteamento tipado e de loaders se estende diretamente ao framework full-stack, com SSR e desidratação adicionados.
3. Table → Query: o Table consome dados paginados e filtrados do Query para paginação no lado do servidor, de modo que o grid lida com grandes conjuntos de dados sem trazer tudo para o cliente.

Escolhendo TanStack vs. as Alternativas Consolidadas

Escolha o TanStack Start para páginas públicas que precisam ser indexadas e compartilhadas, e o TanStack Router isoladamente para dashboards autenticados onde SEO é irrelevante e a performance no lado do cliente é a prioridade. Essa decisão de estratégia de renderização é a primeira escolha arquitetural e precede qualquer escolha de biblioteca — é uma decisão de produto, não uma preferência técnica.

• Sites públicos (páginas de marketing, blogs, produtos de conteúdo) precisam de SSR. Crawlers não executam JavaScript de forma confiável; Core Web Vitals como LCP, CLS e INP são sinais de ranqueamento do Google; e os metadados do Open Graph são lidos a partir da resposta do servidor. O Start entrega HTML totalmente renderizado na primeira requisição.
• Aplicativos autenticados (dashboards, ferramentas internas, portais de clientes) não podem ser rastreados de qualquer forma, são baseados em sessão e com estado, e priorizam o tempo até a interatividade. Uma SPA no Router isoladamente — sem a maquinaria SSR do Start — costuma ser mais enxuta.

Para a questão biblioteca-versus-alternativa consolidada, o ecossistema mapeia claramente para os padrões do React:

Quando Não Usar o TanStack

O modelo headless e type-safe do TanStack é um padrão sólido, mas representa uma desvantagem real em três situações, e um mapa honesto as nomeia. O modelo não é adequado quando sua equipe precisa de componentes pré-estilizados prontos para uso, quando seu pool de contratação conhece Redux e React Router mas não o TanStack, ou quando você precisa de React Server Components estáveis em produção hoje — pois o suporte a RSC no Start ainda é experimental, e o Next.js e o React Hook Form continuam sendo as escolhas mais pragmáticas nesses casos.

Especificamente:

• Necessidade de componentes pré-estilizados: headless significa que você constrói a UI. Se você quer um grid ou formulário com aparência finalizada logo após a instalação, AG Grid, MUI ou um kit de componentes será mais rápido.
• Familiaridade da equipe e contratação: mais desenvolvedores conhecem Redux, React Router e Next.js. A curva de aprendizado e o pool de contratação menor são custos reais para o crescimento da equipe.
• RSC em produção hoje: o Next.js tem anos de battle-testing em produção para React Server Components; o suporte a RSC do Start é experimental em junho de 2026.
• Bibliotecas em estágio inicial: Store (alpha), DB (beta) e AI (beta) ainda não são padrão para produção. Adote-as com essa maturidade em mente e acompanhe a versão e o status nos docs vinculados.

Além das bibliotecas cobertas aqui, o TanStack mantém uma camada de utilitários — incluindo Virtual, Pacer, Ranger e as DevTools — que segue o mesmo padrão headless e type-safe em escopo menor.

Por Onde Começar

Adote o Query primeiro, se ainda não o fez — é a mudança com maior retorno sobre investimento em uma base de código React e não te compromete com mais nada. Opte pelo Router em uma SPA greenfield em vez de migrar um aplicativo existente, e trate o Start como a escolha para novos sites públicos que precisam de SSR, acompanhando seu status de RC. Para as bibliotecas em estágio inicial — Store, DB e AI — deixe que a tabela de maturidade datada e os docs oficiais vinculados, e não o hype do ecossistema, decidam se uma biblioteca está pronta para o papel que você tem em mente.

Perguntas Frequentes

Qual é a diferença entre TanStack Query e TanStack DB?

O TanStack Query gerencia o estado assíncrono do servidor por meio de busca de dados, cache, refetch em segundo plano e deduplicação, tratando o servidor como a fonte de verdade que o cliente espelha. O TanStack DB é um store reativo e client-first com coleções, live queries e mutações otimistas que fica na frente do seu próprio backend para aplicativos intensivos em dados com atualizações em tempo real e filtragem complexa no lado do cliente. O Query é estável; o DB está em beta em junho de 2026.

Posso usar as bibliotecas TanStack com Vue, Svelte ou Angular em vez de React?

Sim, para as bibliotecas de dados e UI. Query, Table, Form, Virtual e Store disponibilizam adaptadores oficiais para React, Vue, Solid, Svelte e Angular. O roteamento é a exceção: o TanStack Router e o framework full-stack TanStack Start têm como alvo apenas React e Solid. Portanto, uma equipe Vue ou Angular pode adotar Query e Table, mas não pode usar o TanStack Router para roteamento type-safe.

O TanStack Start está pronto para produção como substituto do Next.js?

Não completamente, em junho de 2026. O TanStack Start está no estágio de Release Candidate na linha de release 1.168.x, ainda não declarado estável, e seu suporte a React Server Components está disponível apenas de forma experimental, e não como padrão de produção. Se você precisa de RSC estável em produção hoje, o Next.js tem anos de battle-testing para esse recurso. O Start é uma escolha razoável para novos sites públicos com SSR onde RSC experimental é aceitável.

Preciso adotar todo o ecossistema TanStack para usar uma biblioteca?

Não. Cada biblioteca TanStack é independente e composável, portanto você pode adotar o Query sem o Router, ou o Table sem o Start. As bibliotecas se integram quando usadas em conjunto (loaders de rota podem fazer pré-fetch de dados do Query, por exemplo), mas nenhuma delas exige as outras. O Query é o ponto de entrada mais comum porque é a mudança com maior retorno sobre investimento em uma base de código React existente e não te compromete com mais nada no ecossistema.