Migrando do React Router para o TanStack Router
Descubra por que o TanStack Router pode ser uma alternativa moderna e eficiente frente às recentes decisões do React Router.
Por que isso é importante
Com o crescimento das SPAs modernas e a redução de dependência em server-side rendering, desenvolvedores estão revendo o uso de frameworks pesados. O TanStack Router surge como alternativa leve, tipada e eficiente para projetos React, especialmente em dashboards e sistemas autenticados.
O que é o TanStack Router
O TanStack Router é um roteador client-side criado por Tanner Linsley, o mesmo criador do React Query. Ele faz parte de uma suíte completa chamada TanStack, que reúne soluções como tabelas, formulários, virtualização de listas e até banco de dados local.
O cenário do React Router
O React Router passou por mudanças drásticas após a aquisição do Remix. Versões recentes fundem funcionalidades do Remix no core do React Router, criando novos modos de instalação: declarativo, data e framework. Essa fusão aumentou a complexidade e causou confusão na comunidade.
⚠️Atenção
Instalar o React Router hoje pode significar instalar o Remix inteiro, caso opte pelo modo framework. Isso foge do propósito de um roteador simples e modular, principalmente em apps que não dependem de SSR.
Por que migrar para o TanStack Router
A migração para o TanStack Router foi motivada por buscar simplicidade, clareza e ferramentas modernas. O roteador permite tipagem completa, rotas baseadas em arquivos, integração com plugins Vite e uma experiencia de DX muito mais produtiva.
Features que fazem a diferença
Um dos grandes destaques é a tipagem nas rotas. Desde paths até parâmetros e query strings, tudo é inferido com segurança. Além disso, o TanStack Router permite definir titles e metas de cada página com clareza, sem a necessidade de bibliotecas externas nem gambiarras.
ℹ️Importante saber
Criar um novo arquivo na pasta pages já gera uma nova rota. Se o arquivo for esqueci-minha-senha.tsx, a rota /esqueci-minha-senha está pronta, com tipagem gerada automaticamente no TypeScript.
O que o React Router não entrega
Mesmo após tanto tempo, o React Router não possui uma forma oficial de definir títulos de páginas ou metadados. Algumas soluções envolvem hooks e manipulações via useEffect, o que traz problemas de acessibilidade e manutenção.
Diferença entre uso simples e uso como framework
React Router (modo declarativo)
Versão tradicional como biblioteca de rotas apenas client-side
Prós
- Simples para projetos pequenos
- Compatível com versão anterior do React Router
Contras
- Sem tipagem nativa
- Sem suporte a metadados
- Não possui file-based routing
TanStack Router
Nova abordagem moderna focada em produtividade e tipos
Prós
- File-based routing nativo
- Rotas 100% tipadas
- Integração com Vite
- Escalável para grandes apps
Contras
- Menor adoção até o momento
- Curva de aprendizado para iniciantes sem contexto de DX moderna
Implementando do zero no Vite
A configuração envolve adicionar o plugin do TanStack Router no vite.config.ts e criar a estrutura de arquivos em /pages. Cada arquivo automaticamente vira uma rota, com suporte completo a params, searchParams e metadata como title, description e etc.
Exemplo prático: adicionando nova página
Basta criar o arquivo forgot.tsx em pages e a rota /forgot está disponível. O TanStack Router ainda gera a tipagem no arquivo routeTreeGen.ts, mantendo tudo sincronizado e seguro.
✅Atenção
Ao criar arquivos com underline (_) no nome ou na pasta, eles são ignorados como parte da URL — perfeito para layouts como root ou auth.
Recursos e ferramentas úteis
React Query (TanStack Query)
Gerenciador de estado e busca de dados, ideal para apps client-side
Saiba mais →O futuro com TanStack Start
O TanStack Start é a próxima evolução: um framework extensivo sobre o TanStack Router, planejado para substituir soluções como Next.js e Remix. Ele adicionará funcionalidades server-side sob demanda e offline-first integradas.