vue-jsx-best-practices

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

A skill vue-jsx-best-practices ajuda você a evitar o erro mais comum ao escrever JSX em Vue: supor que as convenções de JSX do React se aplicam sem mudanças. Não se aplicam. Em Vue JSX, em geral você usa nomes de atributos HTML padrão, como class e for, e não formas no estilo React como className e htmlFor.

Para quem essa skill é indicada

Esta skill é mais útil para desenvolvedores frontend que:

• escrevem componentes Vue 3 com JSX ou TSX
• migram componentes de React para Vue
• encontram erros de TypeScript relacionados a props e atributos JSX
• querem que render functions em Vue sigam as convenções dos templates Vue

Se o seu trabalho é “deixar este código Vue JSX type-safe e idiomático sem tentativa e erro”, vue-jsx-best-practices é uma ótima escolha.

Que problema ela realmente ajuda a resolver

O trabalho real aqui não é “aprender JSX”. É converter JSX incompleto, misto ou com formato de React em JSX compatível com Vue que:

• passe nas verificações do TypeScript
• siga as convenções do Vue
• evite bugs sutis de migração
• continue legível para times que usam tanto templates quanto render functions

O que diferencia a vue-jsx-best-practices

A skill é específica — e isso é uma vantagem. Em vez de tentar cobrir todos os tópicos de renderização em Vue, ela foca em um ponto de atrito recorrente: em Vue JSX, usam-se nomes de atributos HTML, e não as convenções de nomenclatura do React. Isso dá valor prático quando você está depurando atributos incorretos, revisando código migrado ou padronizando o uso de TSX em uma base de código.

O que saber antes de instalar

Isto não é um guia amplo de arquitetura Vue. Pelas evidências do repositório, trata-se de uma skill enxuta, centrada em um documento de referência: reference/render-function-jsx-vue-vs-react.md. Instale vue-jsx-best-practices se você quer orientação objetiva sobre diferenças de sintaxe em Vue JSX e padrões de migração mais seguros, não um guia completo de JSX.

Como usar a skill vue-jsx-best-practices

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

Use a skill quando seu agente ou fluxo de trabalho estiver gerando, revisando ou migrando Vue JSX/TSX. Um comando prático de instalação é:

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

Depois, acione a skill quando sua tarefa incluir pedidos como:

• “convert this React component to Vue TSX”
• “fix JSX attribute type errors in Vue”
• “review this Vue render function for React-style conventions”
• “make this Vue JSX idiomatic”

Leia primeiro estes arquivos do repositório

Esta skill é pequena, então a ordem de leitura faz diferença:

1. skills/vue-jsx-best-practices/SKILL.md
2. skills/vue-jsx-best-practices/reference/render-function-jsx-vue-vs-react.md

O segundo arquivo concentra a maior parte do valor prático. Ele explica a regra principal, por que o TypeScript detecta o problema e o que deve ser alterado durante a migração.

Que tipo de entrada a skill precisa

vue-jsx-best-practices funciona melhor quando você fornece código real e contexto, não apenas “help with Vue JSX”. Inclua:

• o código-fonte do componente
• se ele é Vue 3
• se você está usando JSX ou TSX
• os erros atuais de TypeScript, se houver
• se o código veio de React
• sua ferramenta de build, como Vite

Entrada mínima útil:

• “This is a Vue 3 TSX component migrated from React. Fix invalid JSX attributes and explain each change.”

Entrada melhor:

• “Review this Vue 3 TSX file migrated from React. Replace React-only JSX conventions with Vue equivalents, preserve behavior, and note anything that will still require plugin or TypeScript config checks in Vite.”

A regra principal que a skill ajuda a aplicar

A principal conclusão prática é simples:

• use class, não className
• use for, não htmlFor
• use nomes de atributos no estilo HTML, alinhados aos templates Vue
• use nomes padrão para handlers de evento com prefixo on, como onClick

Isso importa porque o runtime do Vue pode ser tolerante, mas o TypeScript deve sinalizar as formas no estilo React. E isso é útil: a inconsistência é detectada cedo.

Transforme um objetivo vago em um prompt forte

Prompt fraco:

• “Fix this JSX.”

Prompt forte:

• “Apply vue-jsx-best-practices to this Vue 3 TSX component. Identify any React JSX conventions such as className or htmlFor, replace them with Vue JSX equivalents, keep event handlers intact, and explain which changes are for type safety versus runtime behavior.”

Por que isso é melhor:

• nomeia a origem do problema na migração
• pede substituições concretas
• separa problemas de compilação da tolerância em runtime
• reduz respostas genéricas sobre Vue

Fluxo de trabalho sugerido para tarefas de migração

Um bom fluxo de uso de vue-jsx-best-practices é:

1. Cole o componente original em React ou com JSX misto.
2. Peça uma primeira conversão para as convenções de Vue JSX.
3. Peça uma segunda passada focada apenas em compatibilidade com TypeScript.
4. Compare props, labels e bindings de eventos linha por linha.
5. Rode seu verificador de tipos local e envie os erros restantes de volta para a skill.

Essa abordagem em etapas é melhor do que pedir uma “migração completa” de uma vez só, porque vue-jsx-best-practices é mais forte na limpeza de convenções de JSX do que em reescritas completas entre frameworks.

O que verificar no código convertido

Depois de usar vue-jsx-best-practices, revise:

• labels usando for
• bindings de classes CSS usando class
• nomes de props do DOM copiados do React
• grafia dos handlers de evento
• se a saída ainda assume padrões de componentes do React

A skill pode melhorar sintaxe e convenções, mas você ainda precisa validar lógica específica do framework, como hooks, state e APIs de componentes.

Considerações sobre TypeScript e Vite

O material de origem menciona explicitamente a configuração de TypeScript para inferência de tipos em Vue JSX e a configuração do Vite como temas relevantes. Na prática, isso significa que você não deve tratar erros de atributos como algo apenas estilístico. Se sua configuração de TSX estiver correta, atributos inválidos no estilo React devem aparecer na checagem de tipos. Se isso não acontecer, verifique seu plugin de Vue JSX e a configuração do TypeScript antes de confiar em um resultado que “funciona” só em runtime.

Quando a vue-jsx-best-practices é ideal — e quando não é

Melhor encaixe:

• migração de React para Vue TSX
• code review de convenções de Vue JSX
• correção de erros de atributos JSX em Vue 3
• padronização de estilo de time em render functions

Não é a melhor opção para:

• aprender Vue do zero
• ajuda com sintaxe de templates
• design com Composition API
• troubleshooting completo de setup de build além de configuração relacionada a JSX

Exemplo de pedido que gera uma resposta melhor

Use algo como:

“Use vue-jsx-best-practices on this Vue 3 TSX component. Flag every React-style JSX attribute, replace it with Vue JSX syntax, keep the component behavior unchanged, and give me a short checklist I can apply to the rest of the codebase.”

Esse prompt entrega tanto a correção quanto um padrão de revisão reutilizável.

FAQ da skill vue-jsx-best-practices

A vue-jsx-best-practices serve só para migração de React?

Não. Migração de React é o caso de uso mais evidente, mas a skill também ajuda se seu time escreve Vue TSX diretamente e quer convenções consistentes e seguras em termos de tipos. Ela é útil sempre que nomes de atributos no estilo React aparecem em Vue JSX.

A vue-jsx-best-practices instala um plugin ou muda minha configuração?

Não. A skill fornece orientação; ela não é um pacote que corrige automaticamente sua toolchain. Você continua precisando do seu próprio setup de Vue JSX e TypeScript no app. A skill ajuda a identificar como o código deve ficar quando essa base já está pronta.

Qual é a principal diferença em relação a um prompt comum?

Um prompt comum pode gerar JSX plausível sem respeitar as convenções específicas de atributos do Vue. vue-jsx-best-practices é mais confiável para esse problema específico porque coloca no centro a divergência entre JSX de Vue e React, além das implicações para type safety.

Esta skill é amigável para iniciantes?

Sim, desde que você já conheça o básico de Vue ou JSX. O escopo é restrito o bastante para ser acessível. Mas, se você é totalmente iniciante em renderização no Vue, esta skill não substitui uma introdução mais ampla sobre componentes, templates ou render functions.

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

Pode pular esta skill se sua base usa apenas templates Vue e não trabalha com JSX/TSX. Também não faz sentido usá-la se o problema não tiver relação com nomes de atributos JSX, como roteamento, gerenciamento de estado ou renderização no servidor.

O comportamento em runtime sempre quebra se eu usar atributos no estilo React?

Nem sempre. A referência observa que o runtime do Vue pode ser tolerante e converter alguns atributos corretamente. O problema maior é consistência e type safety: o TypeScript deve rejeitar essas convenções de React em Vue JSX, e isso normalmente é exatamente o que você quer.

Como melhorar o uso da skill vue-jsx-best-practices

Envie código, erros e intenção de framework juntos

A forma mais rápida de melhorar os resultados com vue-jsx-best-practices é fornecer:

• o componente de origem
• o formato desejado no framework de destino
• erros reais do compilador ou do editor
• se o objetivo é migração, limpeza ou revisão

Sem isso, a resposta pode parar em trocas óbvias de atributos e deixar passar suposições ao redor do JSX.

Peça uma revisão orientada a diff

Um prompt de alto valor é:

“Review this file using vue-jsx-best-practices. Do not rewrite everything. Only flag JSX conventions that are invalid, risky, or non-idiomatic in Vue, and explain each change briefly.”

Isso reduz edições excessivas e facilita a revisão em codebases já existentes.

Separe correções de sintaxe de reescritas de framework

Um modo comum de falha é pedir que a skill resolva ao mesmo tempo diferenças de sintaxe em JSX e toda a migração comportamental de React para Vue. Para melhorar a qualidade da saída, separe essas tarefas:

1. normalizar convenções de JSX
2. corrigir erros de tipo
3. refatorar a lógica de framework

Assim, vue-jsx-best-practices permanece focada no que ela realmente cobre bem.

Peça um checklist reutilizável

O repositório já sugere uma lógica de checklist para tarefas. Vá além e peça que a skill gere uma lista de auditoria pronta para o time, por exemplo:

• substituir className por class
• substituir htmlFor por for
• verificar handlers de evento on*
• rodar novamente as checagens de TS nos arquivos convertidos

Isso transforma uma ajuda pontual em um processo de revisão repetível.

Valide suposições de configuração após a primeira passada

Se a saída parecer correta, mas seu editor não sinalizar atributos inválidos, faça uma pergunta complementar sobre as premissas do ambiente TSX. A skill menciona inferência do TypeScript e configuração do Vite como contexto relevante, então uma validação fraca no seu setup local pode esconder erros reais.

Falhas comuns para observar

Fique atento a estes problemas depois de usar vue-jsx-best-practices:

• nomes de atributos do React ainda presentes em elementos aninhados
• saída que “funciona” em runtime, mas falha nas checagens de TS
• orientação de migração que altera comportamento, não só sintaxe
• limpeza incompleta de labels, classes e props do DOM

Esses pontos são bons candidatos para uma segunda rodada de revisão.

Melhore o prompt após a primeira resposta

Um bom prompt de iteração é:

“Now do a second pass with vue-jsx-best-practices focused only on missed React-style JSX conventions and any Vue JSX typing issues. Keep logic unchanged.”

Esse follow-up costuma ser mais eficaz do que pedir uma reescrita totalmente nova.

Use o arquivo de referência como âncora de decisão

Se você estiver em dúvida sobre confiar ou não na saída, compare com:

reference/render-function-jsx-vue-vs-react.md

Esse arquivo é a âncora mais clara para o comportamento esperado da skill. Para decidir se vale instalar, isso também é um bom sinal: a skill é compacta, mas a orientação é específica o suficiente para reduzir erros evitáveis em Vue JSX.