vue-best-practices

Visão geral da skill vue-best-practices

Para que serve vue-best-practices

vue-best-practices é uma skill de instrução focada em Vue para geração de código, revisão e refatoração em projetos Vue 3. O objetivo central não é apenas “escrever código Vue”, mas “escrever código Vue seguindo padrões arquiteturais atuais que continuem sustentáveis sob a pressão de um projeto real”. Na prática, ela conduz o agente para Composition API, <script setup lang="ts">, fluxo de dados explícito e decisões específicas de Vue que prompts genéricos de frontend costumam ignorar.

Quem deve instalar vue-best-practices

Esta skill é mais indicada para equipes e desenvolvedores solo que trabalham com Vue 3, componentes single-file .vue, Vue Router, padrões de estado no estilo Pinia, apps baseados em Vite e aplicações Vue com suporte a SSR. Ela é especialmente útil se você quer que um assistente de IA pare de cair em padrões genéricos de JavaScript e passe a seguir convenções nativas do ecossistema Vue.

O trabalho real que ela resolve

O valor real de vue-best-practices está em reduzir erros de design evitáveis antes mesmo de a implementação começar. A skill orienta explicitamente o agente a confirmar primeiro a arquitetura e, depois, manter algumas referências centrais no contexto ativo: reatividade, estrutura de SFC, fluxo de dados entre componentes e composables. Isso a torna mais útil para decisões de implementação do que um prompt simples do tipo “construa este componente”.

O que diferencia esta skill

O diferencial está no caminho de decisão. A skill não apenas diz “use Vue 3”. Ela define padrões e limites:

• usar por padrão Composition API com <script setup lang="ts">
• trocar de skill se o projeto for explicitamente Options API ou JSX
• tratar props, emits, v-model, provide/inject, componentes assíncronos, transições e performance como preocupações de design de primeira linha
• recorrer a documentação de referência específica para casos de borda, em vez de confiar só na memória

Quando vue-best-practices é uma boa escolha

Use vue-best-practices for Frontend Development quando precisar de ajuda com:

• criar ou refatorar componentes Vue
• decidir entre props/emits, v-model, provide/inject ou store
• desenho de composables
• escolhas de componentes assíncronos com impacto em SSR
• APIs de slots, fallthrough attrs, transições, KeepAlive e performance de listas
• revisar se uma implementação Vue está idiomática, e não apenas funcional

Quando não é a skill certa

Não use vue-best-practices como guia principal se o codebase for intencionalmente centrado em Options API ou em JSX. A própria skill indica carregar outra skill nesses casos, se houver. Ela também não substitui a documentação específica de framework para temas como roteamento em Nuxt, setup de testes ou preocupações de deploy que não estejam cobertas nas referências.

Como usar a skill vue-best-practices

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

Instale o repositório pai de skills e depois invoque a skill vue-best-practices a partir dessa coleção:

npx skills add vuejs-ai/skills --skill vue-best-practices

O caminho no repositório é:
skills/vue-best-practices

Fonte no GitHub:
https://github.com/vuejs-ai/skills/tree/main/skills/vue-best-practices

Leia estes arquivos primeiro

Para uma leitura rápida e de alto sinal, comece por:

• skills/vue-best-practices/SKILL.md
• skills/vue-best-practices/references/reactivity.md
• skills/vue-best-practices/references/sfc.md
• skills/vue-best-practices/references/component-data-flow.md
• skills/vue-best-practices/references/composables.md

Essas quatro referências são tratadas pela própria skill como contexto essencial de leitura obrigatória. Se você as pular, perde a maior parte do valor prático que ela oferece.

Quais informações a skill precisa receber

O uso de vue-best-practices melhora muito quando você fornece contexto arquitetural, e não apenas um pedido de feature. O mínimo útil é:

• versão do Vue e se o projeto é Vue 3
• se o projeto já usa TypeScript
• se o codebase exige Composition API, Options API ou JSX
• contexto de router/store
• contexto de SSR ou client-only
• responsabilidades do componente
• fluxo de dados existente entre pai e filho
• restrições de performance, acessibilidade ou tamanho de bundle

Um prompt fraco só pede um componente. Um prompt forte explica onde esse componente fica no app e como os dados devem circular.

Como transformar um objetivo vago em um prompt forte

Fraco:

• “Build a Vue modal.”

Mais forte:

• “Using vue-best-practices, create a Vue 3 modal component with <script setup lang="ts">. The modal is controlled by the parent via props and emits, must support v-model:open, trap focus, Teleport to body, and avoid mutating props internally. Show the component API, parent usage, and explain why props/emits are better here than provide/inject.”

Essa versão dá à skill contexto suficiente para aplicar sua orientação sobre fluxo de dados e API de componentes.

Melhor fluxo de trabalho para o primeiro uso

Um vue-best-practices guide prático fica assim:

1. Confirme a arquitetura do projeto antes de pedir código.
2. Diga se Composition API é o padrão.
3. Peça que o agente consulte primeiro as referências centrais.
4. Solicite um plano de implementação antes do código se o limite do componente ainda não estiver claro.
5. Gere o componente.
6. Faça uma segunda passada focada em revisão específica de Vue: reatividade, attrs, slots, performance e comportamento em SSR.

Esse fluxo acompanha a ênfase da skill em “confirmar a arquitetura antes de codar”.

Como pedir a decisão arquitetural certa

Esta skill é mais útil quando a pergunta é formulada como uma decisão, e não como um despejo de código. Bons exemplos:

• “Should this state live in the parent, a composable, or Pinia?”
• “Is v-model appropriate here or should this be explicit props/emits?”
• “Should this large list use virtualization?”
• “Is <Transition> correct here, or would class-based animation be simpler?”
• “Should this component be async-loaded in SSR?”

Essas perguntas se conectam diretamente às referências do repositório.

Arquivos de referência que valem ser trazidos por tipo de tarefa

Use estas referências de forma seletiva conforme a tarefa:

• references/component-async.md para lazy loading e timing de hidratação em SSR
• references/component-slots.md para desenho de API de slots e defineSlots
• references/component-fallthrough-attrs.md para $attrs e useAttrs()
• references/component-keep-alive.md para comportamento de cache e risco de estado obsoleto
• references/component-transition.md e references/component-transition-group.md para casos de entrada/saída
• references/animation-class-based-technique.md para efeitos que não dependem de mount/unmount
• references/state-management.md para decisões de ownership de estado
• references/perf-virtualize-large-lists.md para renderização de listas grandes
• references/perf-v-once-v-memo-directives.md para otimização seletiva de renderização

Padrões de prompt práticos que geram respostas melhores

Use prompts que peçam código e raciocínio ao mesmo tempo. Por exemplo:

• “Apply vue-best-practices and explain the chosen data-flow model.”
• “Refactor this component to Composition API with <script setup lang="ts">, and call out any reactivity pitfalls.”
• “Review this .vue file against vue-best-practices and classify issues as architecture, data flow, performance, or API design.”
• “Implement this feature and list which Vue references were used.”

Isso força o assistente a explicitar suas premissas em vez de inventar padrões silenciosamente.

Bloqueios comuns na adoção

O maior bloqueio é o desencontro com o codebase real. Se o seu projeto usa uma versão mais antiga de Vue, é orientado primeiro a Options API ou depende fortemente de JSX/render functions, os padrões da skill podem gerar atrito desnecessário. Outro bloqueio comum é descrever mal a ownership do estado. Muitos erros em Vue surgem quando se pede um comportamento de UI sem dizer quem controla o estado, o que leva a mutação indevida de props ou bindings bidirecionais confusos.

O que verificar depois da geração

Depois de usar a vue-best-practices skill, confira se:

• props não estão sendo mutadas nos componentes filhos
• emits são explícitos e tipados quando houver TypeScript
• watch não está sendo usado onde computed seria mais simples
• composables concentram lógica reutilizável, e não estado compartilhado acidental
• componentes assíncronos não criam uma UX de carregamento ruim
• attrs, slots e transições seguem as convenções de Vue
• as táticas de performance têm justificativa, e não foram aplicadas por modismo

FAQ da skill vue-best-practices

vue-best-practices é amigável para iniciantes?

Sim, mas ela ajuda mais iniciantes quando usada como revisora do que como geradora cega de código. As referências explicam por que certos padrões Vue são preferidos, o que ajuda novos usuários a não aprender anti-patterns cedo demais.

vue-best-practices dá suporte apenas a Vue 3?

Na prática, sim, no seu caminho padrão. A skill é fortemente centrada em Vue 3, Composition API, <script setup>, TypeScript, padrões atentos a SSR, Volar e vue-tsc. Se o seu app é Vue 2 ou está muito focado em migração, ela não é a melhor escolha.

Em que vue-best-practices difere de um prompt normal?

Um prompt comum pode gerar código “parecido com Vue” e até funcional. vue-best-practices dá ao assistente um viés arquitetural específico e uma ordem de leitura. Isso importa em Vue porque erros de reatividade, comunicação entre componentes, attrs, cache e slots muitas vezes parecem corretos no começo, mas envelhecem mal.

vue-best-practices é boa para codebases existentes?

Sim, especialmente para refatorações e revisões. Muitas vezes ela entrega mais valor em componentes já existentes do que em trabalho greenfield, porque ajuda a identificar ownership de estado pouco clara, componentes que cresceram demais e problemas de correção específicos de Vue que passam fácil despercebidos em apps maduros.

Devo usar para tarefas com Pinia, Router e SSR?

Sim, desde que a tarefa ainda seja fundamentalmente sobre arquitetura Vue ou comportamento de componentes. A descrição da skill cobre explicitamente Vue Router, Pinia, Vite com Vue e preocupações relacionadas a SSR. Só inclua essas restrições no prompt para que o agente não assuma um caso client-only mais simples.

Quando não devo usar vue-best-practices?

Evite quando:

• o projeto exige explicitamente convenções de Options API
• o projeto usa JSX como estilo principal de autoria
• você precisa de orientação específica de framework fora das referências do repositório
• você só quer um protótipo rápido e descartável e não se importa com idiomatismo em Vue

Como melhorar a skill vue-best-practices

Dê à vue-best-practices insumos arquiteturais mais fortes

A forma mais rápida de melhorar a qualidade da saída é especificar:

• dono do estado
• limites dos componentes
• expectativas de API entre pai e filho
• exigência de TypeScript
• SSR versus renderização apenas no cliente
• escala esperada, como listas grandes ou views em cache

Sem isso, a skill precisa adivinhar trade-offs de design que ela foi justamente feita para decidir de forma explícita.

Peça um plano antes da implementação

Para trabalhos não triviais, pergunte primeiro:

• a que lugar pertence cada estado
• se a feature deve ser responsabilidade de um componente, composable ou store
• se a comunicação deve usar props/emits, v-model, provide/inject ou estado em router/store

Isso segue a regra do repositório de priorizar arquitetura antes da implementação e normalmente melhora mais a primeira versão do código do que simplesmente pedir “clean code”.

Use a biblioteca de referências de forma intencional

A vue-best-practices skill tem profundidade real na pasta references/. Os resultados melhoram quando você cita o arquivo relevante no prompt:

• “Use component-data-flow.md logic”
• “Check component-async.md because this is SSR”
• “Apply component-fallthrough-attrs.md because this wrapper forwards attrs”
• “Use perf-virtualize-large-lists.md because this table can exceed 5,000 rows”

Essa é uma vantagem prática em relação a prompts genéricos.

Fique atento aos modos de falha mais comuns

As saídas mais fracas costumam aparecer quando o assistente:

• muta props em vez de emitir atualizações
• usa watchers onde estado derivado com computed já resolveria
• escolhe provide/inject cedo demais
• coloca lógica em um componente quando ela deveria estar em um composable
• adiciona transições onde animação baseada em classes seria mais simples
• coloca views em cache com <KeepAlive> sem uma estratégia de atualização de dados
• sugere micro-otimizações prematuras sem evidência

São exatamente esses tipos de problema que esta skill busca reduzir.

Melhore os prompts de revisão após o primeiro rascunho

Depois de gerar o código, peça uma segunda passada como:

• “Review this against vue-best-practices and list the top 5 risks.”
• “Find any reactivity edge cases or data-flow violations.”
• “Check whether this slot API and fallthrough attrs behavior are robust.”
• “Audit this SSR component for async loading and hydration concerns.”

A primeira passada cria código. A segunda extrai o valor real da skill.

Torne a saída mais acionável com entregáveis explícitos

Se você quer um uso de vue-best-practices de maior qualidade, peça:

• código final
• uma justificativa arquitetural curta
• uma lista de alternativas descartadas
• notas de migração se estiver refatorando código existente
• um checklist de verificação para vue-tsc, Volar e comportamento em runtime

Esse formato reduz respostas superficiais e facilita a adoção do resultado em um repositório real.