vue-router-best-practices

Visão geral da skill vue-router-best-practices

Em que a vue-router-best-practices ajuda

A skill vue-router-best-practices é um guia focado de troubleshooting e implementação para Vue Router 4, especialmente em navegação com guards, mudanças de params de rota e comportamento de ciclo de vida de componentes ligados a rotas. Ela é mais útil quando sua aplicação já usa Vue 3 + Vue Router e você precisa chegar rápido aos padrões corretos, não receber conselhos genéricos de framework.

Quem deve instalar esta skill

Esta skill faz sentido para desenvolvedores frontend que estão:

• colocando em produção rotas autenticadas ou protegidas por permissões
• depurando dados desatualizados quando só os params da rota mudam
• migrando código antigo de guards que ainda usa next()
• tentando evitar loops de redirect e bugs silenciosos de roteamento

Se, na prática, o seu trabalho é “deixar o roteamento seguro e previsível em produção”, esta skill é uma opção melhor do que um prompt amplo sobre Vue.

Por que esta skill é diferente de um prompt genérico

O valor da vue-router-best-practices está em concentrar um conjunto pequeno de armadilhas de alto impacto do Vue Router que quebram aplicações reais com frequência:

• beforeEnter não dispara em atualizações de param ou query
• beforeRouteEnter não tem acesso a this
• lógica assíncrona em guards que na prática não bloqueia a navegação
• redirects infinitos em guards globais
• estado stale do componente quando params da rota mudam
• padrões antigos com next() no Vue Router 4

Isso torna a skill especialmente útil para correção de bugs, code review e trabalho de migração.

O que ela não tenta cobrir

Isto não é um curso completo de Vue Router, nem uma referência completa da API de roteamento, nem um guia de arquitetura para todos os modos do router. A proposta da skill é ser estreita por design: ela ajuda com problemas práticos de correção que afetam o comportamento real da navegação.

Como usar a skill vue-router-best-practices

Contexto de instalação da vue-router-best-practices

Use vue-router-best-practices dentro de um fluxo de AI coding em que o modelo consiga inspecionar sua configuração de router, seus route components e a lógica dos guards. A própria skill fica em skills/vue-router-best-practices no repositório vuejs-ai/skills:

• SKILL.md
• reference/router-beforeenter-no-param-trigger.md
• reference/router-beforerouteenter-no-this.md
• reference/router-guard-async-await-pattern.md
• reference/router-navigation-guard-infinite-loop.md
• reference/router-navigation-guard-next-deprecated.md
• reference/router-param-change-no-lifecycle.md
• reference/router-simple-routing-cleanup.md
• reference/router-use-vue-router-for-production.md

Se a sua plataforma oferece instalação de skills, use o fluxo normal de add/import do repositório e depois selecione vue-router-best-practices.

Leia estes arquivos primeiro antes de escrever o prompt

Para entender mais rápido, leia nesta ordem:

1. SKILL.md
2. reference/router-navigation-guard-next-deprecated.md
3. reference/router-navigation-guard-infinite-loop.md
4. reference/router-param-change-no-lifecycle.md
5. reference/router-beforeenter-no-param-trigger.md

Esse caminho de leitura traz primeiro os erros de maior risco: fluxo de controle quebrado em guards, loops de redirect e dados stale dirigidos por rota.

Que entrada a skill precisa

A vue-router-best-practices skill funciona melhor quando você fornece código de roteamento concreto, e não apenas um sintoma. Boas entradas incluem:

• router/index.ts ou router.ts
• route records com meta
• guards globais como beforeEach
• guards dentro do componente
• componentes renderizados por rotas dinâmicas como /users/:id
• uma reprodução curta do que a navegação deveria fazer versus o que faz hoje

Sem código, a resposta tende a ficar mais genérica e menos confiável.

Como transformar um problema vago em um prompt forte

Prompt fraco:

• “My Vue Router is buggy. Help.”

Prompt forte:

• “Use vue-router-best-practices to review this Vue Router 4 setup. When navigating from /orders/1 to /orders/2, access checks do not rerun and stale order data remains visible. We use a route-level beforeEnter, an async beforeEach, and onMounted in OrderDetail.vue. Identify the bug sources, explain which Vue Router behaviors are causing them, and rewrite the guards and component logic using Vue Router 4 return-based patterns.”

Essa versão dá estrutura suficiente para o modelo aplicar o arquivo de referência certo e produzir uma correção realmente aproveitável.

Melhor fluxo de trabalho para usar vue-router-best-practices

Um fluxo prático:

1. Cole a configuração de rota com falha e o código dos guards.
2. Descreva exatamente qual caminho de navegação falha.
3. Peça ao modelo para mapear o problema para uma das armadilhas conhecidas.
4. Solicite uma implementação corrigida.
5. Peça uma checklist curta de testes cobrindo acesso direto, mudança de param na mesma rota, redirects e acesso não autorizado.

Esse fluxo funciona melhor do que pedir “best practices” de forma abstrata, porque a maioria dos bugs de Vue Router depende do cenário.

Casos de uso em que esta skill é mais forte

Os melhores cenários de vue-router-best-practices usage são:

• roteamento com auth e por papel de usuário
• páginas de detalhe dirigidas por route params
• limpeza de código na migração de Vue Router 3 para 4
• depuração de instâncias de componente reutilizadas
• substituição de fluxo de controle frágil com next()
• revisão para decidir se a lógica de guard deve ficar globalmente, por rota ou no componente

Padrões comuns que a skill consegue corrigir

Espere que esta skill ajude você a decidir entre:

• beforeEach vs beforeEnter vs onBeforeRouteUpdate
• watch(() => route.params.id) vs forçar remount com :key
• guards baseados em retorno vs next() depreciado
• fetch no nível do componente vs pré-validação no nível do guard
• Vue Router vs roteamento simples por hash para aplicações em produção

São escolhas reais de implementação, não recomendações apenas de estilo.

Modelo prático de prompt para respostas melhores

Use este modelo para obter resultados melhores com o vue-router-best-practices guide:

• “Use vue-router-best-practices on this Vue 3 app.”
• “Environment: Vue 3, Vue Router 4, Composition API.”
• “Problem: [describe exact navigation bug].”
• “Expected behavior: [what should happen].”
• “Current behavior: [what actually happens].”
• “Files: [paste router config and affected component].”
• “Please: identify the Vue Router gotcha, explain why it happens, propose the safest fix, and include edge cases to test.”

Dicas que melhoram de fato a qualidade do resultado

Passe ao modelo estes detalhes, se você tiver:

• se a rota muda de path ou apenas params/query
• se o componente é reutilizado entre IDs
• se a autenticação é síncrona ou depende de API
• se você está usando Options API ou Composition API
• se o código ainda depende de next()

Esses detalhes determinam diretamente qual orientação de vue-router-best-practices install e uso se aplica ao seu caso.

FAQ da skill vue-router-best-practices

A vue-router-best-practices é boa para iniciantes

Sim, se você já conhece o básico de Vue e precisa de ajuda com comportamentos de roteamento que não são óbvios. Ela não é uma introdução passo a passo ao Vue Router, mas funciona bem para iniciantes diante de erros comuns de produção, porque as referências são organizadas em torno de bugs específicos e suas correções.

Quando devo usar isto em vez de um prompt normal de coding

Use vue-router-best-practices quando o problema envolver transições de rota, timing de guards, route components reutilizados ou comportamento de redirect. Um prompt normal pode sugerir código plausível, mas esta skill tem mais chance de capturar edge cases específicos de Vue Router, como navegação só com mudança de param sem disparar novamente beforeEnter.

Esta skill cobre Vue Router 4 especificamente

Sim. O material-fonte mira explicitamente padrões de Vue Router 4, incluindo a migração para longe do estilo depreciado com next() em favor de guards baseados em retorno.

Quais são os maiores riscos que ela ajuda a evitar

Os problemas de maior valor que ela ajuda a evitar são:

• acesso não autorizado porque os guards não são executados novamente
• dados desatualizados na página ao mudar params
• verificações assíncronas de navegação travadas ou disparando de forma incorreta
• loops infinitos de redirect
• mal-entendidos de ciclo de vida em beforeRouteEnter

Quando esta skill é uma escolha ruim

Pule esta skill se o seu problema for principalmente:

• roteamento SSR com abstrações específicas de framework
• arquitetura geral de componentes Vue sem relação com navegação
• um tutorial completo de roteamento desde os fundamentos
• bibliotecas de roteamento frontend que não são Vue

Esta é uma skill direcionada de vue-router-best-practices for Frontend Development, não um manual universal de roteamento.

Como melhorar a skill vue-router-best-practices

Informe cenários de navegação, não apenas dumps de código

Para melhorar as respostas da vue-router-best-practices, descreva a transição de rota exata:

• de qual URL
• para qual URL
• se só params/query mudaram
• se o usuário deve ser redirecionado, bloqueado ou liberado

Isso importa porque muitos bugs de Vue Router só aparecem em um caminho específico de navegação.

Inclua tanto o código do router quanto o do componente

Um modo frequente de falha é diagnosticar apenas metade do problema. Por exemplo, um route guard pode estar correto enquanto o componente ainda depende de onMounted e exibe dados stale após navegar de /users/1 para /users/2. Inclua os dois arquivos para que a skill consiga conectar a lógica do guard ao comportamento de ciclo de vida do componente.

Peça uma decisão, não só uma correção

Prompt melhor:

• “Should this logic live in beforeEach, beforeEnter, onBeforeRouteUpdate, or a watch, and why?”

Isso gera uma resposta melhor do que “fix this bug”, porque a skill é especialmente útil para escolher a camada certa de roteamento.

Fique atento a estes modos de falha comuns

Os problemas mais comuns a verificar após a primeira resposta:

• a correção ainda assume que beforeEnter roda em mudanças de param
• a solução mistura next() com padrões baseados em retorno
• o redirect de auth ainda pode apontar para a rota atual
• verificações assíncronas são aguardadas, mas erros/timeouts não são tratados
• dados stale são “corrigidos” com remount forçado quando um watch mais leve resolveria

Peça uma checklist de testes depois do patch

Um bom passo de melhoria é:

• “Now give me a minimal test checklist for direct visit, authenticated visit, unauthenticated redirect, same-route param change, query change, and invalid ID.”

Isso é especialmente importante no uso da vue-router-best-practices skill, porque muitos bugs de roteamento só aparecem depois que o fluxo feliz inicial já parece funcionar.

Use as referências como apoio de revisão direcionada

Depois de receber uma primeira resposta, peça ao modelo para validá-la contra a referência mais relevante:

• router-beforeenter-no-param-trigger.md
• router-navigation-guard-infinite-loop.md
• router-param-change-no-lifecycle.md

Essa segunda passada costuma capturar erros sutis e aumenta a confiança antes de você editar código de roteamento em produção.