TanStack Start: 6 diferenças em relação ao Next.js

48% dos watchers de um vídeo sobre frameworks React não são inscritos, mas o tema rendeu: o TanStack Start chamou atenção de quem vinha do Next.js. O framework, criado por Tanner Linsley, aposta em uma premissa simples: tudo o que uma rota precisa — dados, parâmetros e busca — vive em um único lugar, tipado de ponta a ponta.

O que é o TanStack Start e a quem ele se destina

O TanStack Start é um framework full-stack para React criado por Tanner Linsley, o mesmo autor do TanStack Query. Ele roda sobre o TanStack Router e o Vite, e se posiciona como uma alternativa ao Next.js para quem quer SSR, data fetching e tipagem de ponta a ponta sem trocar de modelo mental a cada versão.

Este artigo é um overview, não um curso. O conteúdo acompanha o raciocínio de quem já conhece o Next.js e quer entender, em uma leitura, como o TanStack Start organiza rotas, dados, cache e deploy. Se você quer se aprofundar em frameworks modernos, o Bootcamp do Dev Doido e o Crazystack Typescript, disponíveis em Crazystack, são caminhos de estudo complementares citados pela comunidade brasileira — inclusive por quem acompanha criadores como Gustavo Dev Doido.

A premissa central do framework é a explicitação: tudo o que uma rota precisa — loader, autenticação, search params, pré-renderização — fica declarado dentro da definição da rota. Isso elimina o efeito de espalhar configuração por arquivos soltos, algo que desenvolvedores que mantêm projetos grandes no Next.js costumam sentir na prática.

Como funciona o roteamento baseado em arquivos com createFileRoute

Você cria uma rota de duas formas no TanStack Start. A primeira é criar um arquivo dentro de src/routes, por exemplo about.tsx, e exportar uma constante que chama createFileRoute, importada do pacote do framework. Você passa o caminho da página, como /about, e um objeto com o componente.

A segunda forma é a rota dinâmica. Para uma página de detalhe, você cria o arquivo todos/$todoId.tsx. O segmento $todoId define o parâmetro, e dentro do componente você acessa o valor com a opção params da própria rota. O valor chega tipado como string: se você passar um número no link, o TypeScript acusa erro antes do build.

Depois de criar ou renomear rotas, você roda o comando de desenvolvimento (por exemplo, pnpm run dev). Nesse momento o TanStack Start gera automaticamente o routeTree, um arquivo com todas as rotas da aplicação e seus tipos. É esse arquivo gerado que alimenta a navegação tipada descrita na próxima seção.

Essa geração automática é a base do contrato de tipagem do framework. Sem ela, o autocomplete de rotas não existe; com ela, toda a aplicação compartilha um mapa único de caminhos conhecidos pelo compilador.

Navegação 100% tipada: Link, useNavigate e parâmetros

Para navegar, você importa o componente Link do TanStack Router e usa a propriedade to. O autocomplete oferece todas as rotas geradas no routeTree, inclusive rotas dinâmicas. Ao navegar para /todos/$todoId, você precisa passar o objeto params, e o campo todoId aparece tipado.

O mesmo vale para o useNavigate, útil quando a navegação acontece em código e não em um clique de link. Passar um valor de tipo errado em qualquer um desses pontos gera erro de TypeScript imediatamente, o que reduz uma classe inteira de bugs de rota quebrada que só aparecem em runtime em outros stacks.

Essa tipagem de navegação é um dos pontos que o autor do vídeo sentiu falta no Next.js. Lá, caminhos de Link e objetos de params dependem de convenções e testes manuais; aqui, o compilador garante a consistência entre a declaração da rota e todos os pontos que a referenciam.

Renderização e hydration: a diferença em relação ao Next.js

No primeiro acesso, o servidor renderiza o componente e envia o HTML ao cliente sem interatividade. Depois, o processo de hydration adiciona event listeners e torna a página interativa — o mesmo fluxo que você conhece do Next.js.

A diferença importante é que não existe a divisão entre client components e server components. Todos os componentes podem ter interatividade por padrão: um useState funciona em qualquer arquivo de rota sem erro e sem diretivas. Se você vem do Next.js, essa é provavelmente a maior mudança de modelo mental.

A segunda diferença está na navegação subsequente. Depois do primeiro carregamento, as trocas de página acontecem no cliente, como em uma SPA tradicional. Na prática: primeiro acesso vem do servidor com hydration; navegações seguintes são client-side. Isso explica por que o loader de uma rota roda em ambientes diferentes dependendo do momento, como você verá a seguir.

Loaders, beforeLoad e getRouteApi na definição da rota

O createFileRoute aceita um loader assíncrono, que pode chamar uma API ou buscar dados. O que o loader retorna fica disponível no componente por meio de route.useLoader, já com tipo inferido: se o loader devolve um objeto com message, o componente enxerga data.message tipado.

Uma regra prática acompanha esse loader: ele roda tanto no servidor quanto no cliente. No primeiro acesso ele executa no servidor; em navegações seguintes, executa no cliente. Por isso você não pode chamar o banco de dados diretamente dentro dele — o código precisa funcionar nos dois ambientes. Acesso a banco deve ficar atrás de uma API ou de server functions.

Para autenticação, existe o beforeLoad, que executa antes do loader. Ali você verifica se o usuário está autenticado e, se não estiver, redireciona para outra página. Como tudo fica declarado na rota, fica simples revisar quem pode acessar o quê.

Componentes filhos também conseguem os dados do loader. Em um componente Message qualquer da árvore, você chama getRouteApi passando a rota (por exemplo, /about) e usa routeApi.useLoader(). A requisição não é repetida: o mesmo dado circula pela árvore de componentes sem prop drilling e sem refetch.

validateSearch e a integração com TanStack Query

No ecossistema Next.js, muita gente usa o nuqs, biblioteca de search params para guardar estado na URL — filtros de tabela, modal aberto, paginação. No TanStack Start você não precisa de uma biblioteca extra: o método validateSearch tipa os search params da URL, normalmente com um schema do Zod.

Com o schema declarado, você lê os parâmetros com route.useSearch e recebe tudo tipado. Um parâmetro como ?creating=1 chega convertido para boolean, porque o Zod declarou o tipo. Se você passar o valor errado em código, o TypeScript acusa. Isso cobre o caso clássico de URL state: recarregar a página e manter o filtro, ou compartilhar um link que abre o modal já aberto.

A integração com o TanStack Query é o outro destaque. Dentro do loader, você chama ensureQuery passando a query que já usaria no useQuery. O QueryClient é compartilhado entre servidor e cliente: o servidor começa a buscar a query durante a renderização e vai transmitindo (streaming) os dados ao cliente, reduzindo o tempo de loading e evitando o flash de interface vazia. No componente, você consome o resultado com useSuspenseQuery passando a mesma query.

O cache também é explícito. Para pré-renderizar uma página — o equivalente ao static site generation — você declara um prerender com as rotas desejadas. Para cache HTTP, você define headers de cache-control na rota, o que também permite um comportamento semelhante ao ISR do Next.js. Tudo fica visível na definição da rota, em vez de implícito em convenções.

Deploy do TanStack Start: adapters para qualquer nuvem

O TanStack Start é enfático em um ponto: você pode fazer deploy em qualquer lugar. O projeto usa o Nitro como camada de deployment, e cada provedor tem um adapter mantido pelo próprio framework. Isso reduz o risco de ficar preso a uma única plataforma — uma preocupação comum entre quem avalia o Next.js e a Vercel.

As opções citadas incluem:

• Vercel
• Netlify
• Cloudflare Workers
• Firebase, AWS e outros provedores suportados pelos adapters do Nitro

Na prática, o fluxo típico de deploy segue três passos: você escolhe o adapter do provedor no arquivo de configuração do Vite; roda o build do projeto; e aponta o serviço de hospedagem para o output gerado. Em plataformas como Vercel e Netlify, o build detecta o framework e o processo fica quase automático. Na comparação direta com o Next.js, a diferença está na filosofia: em vez de uma plataforma oficial preferencial, o TanStack Start mantém adapters equivalentes para vários provedores.

Vale uma nota de escopo: desempenho e suporte variam por provedor e por recurso. O que o framework garante é o caminho de build e deploy; SLAs, limites de runtime e preços são de cada plataforma.

TanStack Start ou Next.js: resumo comparativo

A tabela abaixo resume as diferenças que mais afetam a decisão de quem já trabalha com Next.js:

Dimensão	TanStack Start	Next.js
Componentes	Todos interativos por padrão, sem server components	Divisão entre client e server components
Tipagem de rotas	Autocomplete e validação completa via routeTree gerado	Tipagem parcial, depende de convenções
Search params	validateSearch nativo com schemas do Zod	Requer biblioteca externa como nuqs
Cache de dados	QueryClient compartilhado entre servidor e cliente via TanStack Query	Soluções próprias ou bibliotecas da comunidade
Deploy	Adapters do Nitro para múltiplos provedores	Integração mais profunda com a Vercel
Base	TanStack Router + Vite	Framework próprio com compilador dedicado

Não há veredito único. Se sua equipe já domina server components e depende de recursos específicos do Next.js, a migração precisa de justificativa forte. Se você valoriza tipagem explícita, cache previsível e liberdade de hospedagem, o TanStack Start merece um projeto piloto.

FAQ

• O TanStack Start substitui o Next.js? Ele é uma alternativa madura para aplicações React full-stack, mas não uma substituição automática. Times que dependem de server components, image optimization e do ecossistema Vercel tendem a permanecer no Next.js; projetos que priorizam tipagem e portabilidade de deploy se beneficiam do TanStack Start.

• O loader roda no servidor ou no cliente? Nos dois. No primeiro acesso à página ele executa no servidor; em navegações seguintes, roda no cliente, porque a navegação é client-side. Por isso o loader não deve acessar o banco de dados diretamente.

• Preciso de uma biblioteca de search params no TanStack Start? Não. O método validateSearch, combinado com um schema do Zod, tipa os parâmetros da URL e fornece leitura tipada via route.useSearch.

• Em quais provedores eu posso fazer deploy? O framework usa adapters do Nitro mantidos pelo próprio projeto, com suporte para Vercel, Netlify, Cloudflare Workers, Firebase, AWS e outros provedores.

• Como o TanStack Start se integra ao TanStack Query? Você chama ensureQuery no loader, e o QueryClient é compartilhado entre servidor e cliente. O servidor inicia o fetch e faz streaming dos dados; no componente, você consome com useSuspenseQuery.

Do vídeo ao artigo escrito

Este overview mostrou como o TanStack Start concentra rota, dados e cache em um único ponto tipado da aplicação. Se você produziu um vídeo com esse tipo de explicação — comparativos de frameworks, walkthroughs de código, decisões de arquitetura —, esse conhecimento merece existir também em texto, onde mecanismos de busca e leitores podem encontrá-lo.

O Skala Blog resolve exatamente isso: você cola a URL do vídeo do YouTube, ele transcreve o conteúdo e gera um artigo estruturado e pronto para revisão. O fluxo é simples — vídeo, transcrição, artigo — e preserva a sequência de raciocínio que já funcionou na versão falada.

Source video