TanStack React Router: crie rotas tipadas sem misturar APIs

ANÁLISE EDITORIAL

Uma tela React ganhou uma rota filha e, depois da mudança, o link continua abrindo a página, mas o parâmetro de busca deixa de ser validado e o tipo do destino vira uma string genérica. A Skill oficial react-router, do repositório TanStack/router, ajuda um agente de programação a revisar esse caminho inteiro: árvore de rotas, geração de arquivos, registro dos tipos, navegação e hooks. Ela fornece instruções e exemplos; não instala o roteador, não executa testes e não prova que uma alteração ficou correta sem inspeção no projeto.

O que a Skill faz

O documento mantido no repositório oficial descreve como ligar RouterProvider a uma árvore de rotas, usar Link e useNavigate, ler parâmetros com os hooks apropriados e tratar estados de carregamento e erro. Seu alerta mais útil é conceitual: @tanstack/react-router não é o pacote react-router, e seus loaders são orientados ao cliente por padrão. Misturar APIs das duas bibliotecas pode produzir sugestões que parecem plausíveis, mas não compilam.

O arquivo exige a leitura prévia de router-core. Por isso, o ZIP local preserva a estrutura oficial com o núcleo e nove referências temáticas sobre parâmetros, navegação, carregamento, autenticação, divisão de código, erros, tipos e renderização no servidor. Inclui ainda as referências de composição com TanStack Query e de TanStack Start que esses documentos apontam por links relativos, para não entregar uma árvore quebrada. Isso não significa que o agente precise carregar tudo em toda tarefa. O núcleo orienta a escolher a referência pertinente, por exemplo search-params ao mexer na URL e auth-and-guards ao proteger uma rota.

Para quem serve e quando não usar

É uma ferramenta de leitura para desenvolvedores que já usam TanStack Router em React ou avaliam adotá-lo em um projeto. Ajuda quando um agente precisa adicionar uma rota sem perder inferência de tipos, diagnosticar navegação que aponta para um caminho errado ou revisar a diferença entre dados de loader e estado de componente. Também serve como checklist para pedir uma alteração pequena, com arquivos afetados e testes propostos.

Não a aplique como receita automática em um projeto que usa React Router tradicional, Next.js App Router ou outra convenção de roteamento. Uma migração de framework é decisão arquitetural, não consequência de instalar uma Skill. Ela tampouco substitui a documentação atual: o repositório avança, enquanto esta cópia fica fixada em um commit e os próprios frontmatters dos documentos citam versões diferentes.

Compatibilidade e pré-requisitos

A documentação oficial de início rápido informa React e React DOM 18 ou superiores para o pacote React e recomenda TypeScript 5.3 ou superior para a melhor experiência de tipos. O ZIP é texto em formato SKILL.md, que deve ser colocado em um cliente de agente capaz de ler Skills locais. Ele não inclui React, Node.js, TanStack Router, plugin de Vite, servidor MCP ou qualquer dependência executável.

Antes de pedir mudanças, identifique no package.json as versões realmente instaladas e se a aplicação usa rotas por arquivo ou por código. Leia a configuração de Vite ou do bundler, a localização de routeTree.gen.ts e as regras de teste do repositório. O arquivo React da cópia declara 1.166.2; o núcleo declara 1.171.15. Essa diferença está no material de origem. Não trate o ZIP como certificação para uma versão específica da sua aplicação.

Instalação e configuração

Baixe o pacote documental hospedado no Bastidores e compare o SHA-256 informado abaixo. Abra ORIGEM.md e LICENSE antes de extrair. Preserve a árvore packages/react-router/skills/react-router e packages/router-core/skills/router-core, pois o documento principal aponta para o núcleo por caminho relativo. Configure o cliente de agente para ler a Skill principal nessa árvore, conforme as instruções do próprio cliente. Se o cliente exigir uma pasta plana, adapte apenas a instalação local e confira todos os links relativos antes de confiar nela.

Para instalar a biblioteca em um projeto React, siga separadamente a instalação oficial com Vite. Ela mostra o pacote de roteamento, o plugin do bundler e a ordem do plugin antes do plugin React. A Skill não executa esses comandos. Peça ao agente para apresentar um plano e um diff mínimo antes de alterar package.json, rotas ou configuração. Quando usar geração por arquivos, deixe o plugin gerar a árvore; não edite routeTree.gen.ts à mão.

Primeiro uso e resultado esperado

Uma primeira tarefa segura é somente leitura: “Leia a Skill react-router e a referência router-core. Neste projeto, encontre a rota de produtos e explique por que o parâmetro page perde validação ao navegar. Aponte os arquivos e proponha o menor diff, sem editar nem instalar pacotes.” O resultado esperado é uma hipótese ligada aos arquivos reais, com o tipo de rota e a forma de validação identificados. Se faltar contexto, a resposta deve dizer o que precisa ser inspecionado, não inventar o código da aplicação.

Depois da revisão humana, autorize uma mudança pequena em branch de trabalho. Compare o diff, rode a geração de rotas configurada no projeto, o typecheck, os testes pertinentes e o build. A documentação de criação do roteador mostra que o registro da instância em Register é importante para a inferência. Se o agente disser que a navegação está “100% segura” apenas porque o editor não mostrou erro, peça a evidência dos comandos e um teste de clique ou navegação em ambiente de teste.

Não executamos um aplicativo React nem medimos desempenho com este pacote. Auditamos o conteúdo documental, a origem, a licença e a integridade do ZIP. O efeito no projeto depende da versão, configuração e testes do leitor.

Permissões, privacidade e riscos

Os arquivos do ZIP são Markdown e licença, sem código executável. O agente que os lê, porém, pode receber acesso a terminal, rede e arquivos. Comece com leitura limitada à pasta do projeto. Só depois de aprovar o plano conceda edição. Instalação de dependências, atualização do roteador e publicação de uma aplicação são ações separadas. Proteja segredos em .env e não envie dados de usuários nas amostras de rotas ou logs.

Rotas de autenticação exigem atenção maior. Uma checagem no cliente pode melhorar a navegação, mas não substitui autorização no servidor para dados protegidos. Ao alterar loaders e busca, observe cache, redirecionamentos e estados de erro. A documentação de divisão de código também ressalta que separar um loader muda quando ele fica disponível; não prometa redução de bundle ou melhora de tempo sem medição no build real.

Erros comuns e limites

Se o agente disser que não encontra router-core, confira se a árvore packages foi preservada depois da extração. Copiar apenas o primeiro SKILL.md quebra o contexto de que ele depende. Se a navegação perder os tipos, confira se a árvore gerada está importada e se Register aponta para a instância correta. Se uma rota nova não aparecer, verifique a convenção de nomes de arquivo, execute a geração configurada e reinicie o processo de desenvolvimento quando necessário.

Outro problema é usar react-router-dom em uma sugestão voltada a @tanstack/react-router. Rejeite o diff e peça ao agente que compare os imports com o package.json. Se a página renderizar, mas um parâmetro de busca vier inesperado, revise o esquema de validação e os links que constroem a URL. Para falhas de SSR ou autenticação, carregue a referência específica do núcleo e teste também o comportamento do servidor, não apenas o navegador. Se a API citada no documento não corresponder à versão instalada, consulte a documentação da versão do projeto antes de atualizar pacotes.

Versão, licença e download local

A cópia foi fixada no commit 18154b1c45454a70aa77e9d6d27c8a6e0733d031 do repositório oficial TanStack/router. Na consulta de 16 de outubro de 2026, a API do GitHub registrou 15.204 estrelas; esse número é um retrato da data, não uma medida de qualidade do seu projeto. A licença MIT permite a redistribuição dos documentos com o aviso preservado.

O ZIP local contém a Skill React e suas referências Markdown interligadas, LICENSE e ORIGEM.md. Não contém biblioteca, instalador, binário, scripts, dependências nem credenciais. SHA-256 do arquivo: a39bb4ccf0e3bdbbcdfae35f44ea3ceffbe8f79fa6db820cbfc26ab09846948b. Compare o hash após baixar e leia a lista de hashes individuais em ORIGEM.md.

Fontes primárias

Foram consultados o SKILL.md principal, a referência router-core, a documentação oficial de início e a licença. O botão do repositório oficial no card é separado do download do Bastidores e abre a fonte mantida pela TanStack.