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

> Published 2026-10-11T13:55:48.890Z on https://www.crazystack.com.br/pt/p/tanstack-start-6-diferencas-em-relacao-ao-next-js/
> Source video: https://www.youtube.com/watch?v=WZrjigACgFI

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](https://tanstack.com/start) é um framework full-stack para React criado por Tanner Linsley, o mesmo autor do [TanStack Query](https://tanstack.com/query). Ele roda sobre o [TanStack Router](https://tanstack.com/router) e o [Vite](https://vite.dev), e se posiciona como uma alternativa ao [Next.js](https://nextjs.org) 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](https://crazystack.com.br), 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](https://nuqs.47ng.com), 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](https://zod.dev).

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](https://nitro.build) 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](https://vercel.com).

As opções citadas incluem:

- [Vercel](https://vercel.com)
- [Netlify](https://www.netlify.com)
- [Cloudflare Workers](https://workers.cloudflare.com)
- 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](https://skalablog.com) 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](https://www.youtube.com/watch?v=WZrjigACgFI)