Migração do React Router para TanStack Router
o TanStack Router pode ser uma alternativa moderna e eficiente frente às recentes decisões do React Router.
Por que isso é importante
Migração do React Router para TanStack Router. o TanStack Router pode ser uma alternativa moderna e eficiente frente às recentes decisões do React Router.
O que é o TanStack Router
TanStack Router é um roteador client-side feito por Tanner Linsley — sim, o mesmo cara
do React Query. Faz parte da suíte TanStack, que traz soluções pra tabelas, forms,
virtualização de listas e até banco de dados local.
O cenário do React Router
Depois da aquisição do Remix, o React Router mudou bastante. Versões recentes misturam
funcionalidades do Remix direto no core, criando novos modos: declarativo, data e
framework. Essa fusão gerou complexidade e deixou muita gente confusa.
Atenção
Instalar React Router hoje pode significar trazer o Remix inteiro junto, se você
escolher o modo framework. Meio que foge da proposta de um roteador simples, ainda
mais em apps que não usam SSR.
Por que migrar para o TanStack Router
A migração veio da busca por simplicidade e ferramentas mais modernas. TanStack Router
traz tipagem completa, rotas baseadas em arquivos, integração com Vite e uma DX bem
mais produtiva.
- Passo 1: Plugin Vite para transformar arquivos da pasta pages
em rotas automaticamente - Passo 2: Rotas tipadas, com autocompletar e paths validados em
tempo de desenvolvimento - Passo 3: Componente outlet e metadata controlados por arquivo,
sem hacks com useEffect
Features que fazem a diferença
O grande destaque é a tipagem nas rotas. Paths, parâmetros, query strings — tudo
inferido com segurança. TanStack Router também deixa você definir titles e metas de
cada página direto, sem libs externas ou gambiarras.
Importante saber
Criar um arquivo novo na pasta pages já gera uma rota nova. Se o arquivo for
esqueci-minha-senha.tsx, a rota /esqueci-minha-senha já tá pronta com tipagem gerada
automaticamente no TypeScript.
O que o React Router não entrega
Mesmo depois de tanto tempo, React Router não tem forma oficial de definir títulos de
páginas ou metadados. Muita gente usa hooks e manipula via useEffect, o que acaba
trazendo problema 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 config envolve adicionar o plugin do TanStack Router no vite.config.ts e criar a
estrutura de arquivos em /pages. Cada arquivo vira rota automaticamente, com suporte
completo a params, searchParams e metadata tipo title, description, etc.
Exemplo prático: adicionando nova página
Só criar o arquivo forgot.tsx em pages e a rota /forgot já tá disponível. TanStack
Router ainda gera a tipagem no arquivo routeTreeGen.ts, mantendo tudo sincronizado e
seguro.
Atenção
Criar arquivos com underline (_) no nome ou na pasta faz eles serem ignorados na URL
— ótimo pra layouts tipo root ou auth.
Recursos e ferramentas úteis
O futuro com TanStack Start
TanStack Start é a próxima evolução: um framework completo sobre o TanStack Router,
planejado pra competir com Next.js e Remix. Vai trazer funcionalidades server-side sob
demanda e offline-first integradas.
Checklist de Implementação
- Definiu a estrutura de rotas com base em arquivos
- Aplicou tipagem automática das rotas
- Substituiu React Router por TanStack Router com sucesso
- Verificou metadata e carregamento com Vite Plugin
- Testou suas rotas com parâmetros dinâmicos e segurança de tipos
- Criou páginas novas com criação automática de paths e componentes
Perguntas frequentes
O que é o TanStack Router
TanStack Router é um roteador client-side feito por Tanner Linsley — sim, o mesmo cara do React Query. Faz parte da suíte TanStack, que traz soluções pra tabelas, forms, virtualização de listas e até banco de dados local.
Por que migrar para o TanStack Router
A migração veio da busca por simplicidade e ferramentas mais modernas. TanStack Router traz tipagem completa, rotas baseadas em arquivos, integração com Vite e uma DX bem mais produtiva.
O que o React Router não entrega
Mesmo depois de tanto tempo, React Router não tem forma oficial de definir títulos de páginas ou metadados. Muita gente usa hooks e manipula via useEffect, o que acaba trazendo problema de acessibilidade e manutenção.