vue-jsx-best-practices

Présentation de la skill vue-jsx-best-practices

La skill vue-jsx-best-practices vous aide à éviter l’erreur la plus fréquente quand on écrit du JSX dans Vue : supposer que les conventions JSX de React s’appliquent telles quelles. Ce n’est pas le cas. En Vue JSX, on utilise en général les noms d’attributs HTML standard comme class et for, et non les formes propres à React comme className et htmlFor.

À qui s’adresse cette skill

Cette skill convient surtout aux développeurs frontend qui :

• écrivent des composants Vue 3 en JSX ou TSX
• migrent des composants de React vers Vue
• rencontrent des erreurs TypeScript autour des props et attributs JSX
• veulent que les render functions Vue restent alignées avec les conventions des templates Vue

Si votre objectif est de « rendre ce code Vue JSX sûr côté types et idiomatique sans avancer par essais/erreurs », vue-jsx-best-practices est un très bon choix.

À quoi elle sert concrètement

Le vrai besoin n’est pas « apprendre JSX ». Il s’agit plutôt de transformer un JSX approximatif, hybride ou calqué sur React en un Vue JSX compatible qui :

• passe les vérifications TypeScript
• respecte les conventions Vue
• évite des bugs de migration subtils
• reste lisible pour des équipes qui utilisent à la fois les templates et les render functions

Ce qui différencie vue-jsx-best-practices

La skill est volontairement ciblée, et c’est ce qui fait son intérêt. Au lieu de couvrir tout le rendu dans Vue, elle se concentre sur un point de friction très courant : en Vue JSX, on utilise les noms d’attributs HTML, pas les conventions de nommage React. C’est particulièrement utile quand vous déboguez des attributs incorrects, relisez du code migré ou cherchez à standardiser l’usage de TSX dans une base de code.

Ce qu’il faut savoir avant de l’installer

Ce n’est pas un guide général d’architecture Vue. Le dépôt montre une skill compacte centrée sur un document de référence principal : reference/render-function-jsx-vue-vs-react.md. Installez vue-jsx-best-practices si vous cherchez un guidage précis sur les différences de syntaxe entre Vue JSX et React JSX, ainsi que sur des schémas de migration plus sûrs — pas un guide JSX exhaustif.

Comment utiliser la skill vue-jsx-best-practices

Dans quel contexte installer vue-jsx-best-practices

Utilisez cette skill lorsque votre agent ou votre workflow génère, relit ou migre du Vue JSX/TSX. Une commande d’installation pratique est :

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

Ensuite, invoquez-la lorsque votre tâche contient des formulations du type :

• « 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 »

Quels fichiers du dépôt lire en priorité

La skill est petite, donc l’ordre de lecture compte si vous voulez aller vite :

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

C’est surtout le second fichier qui concentre la valeur pratique. Il explique la règle clé, pourquoi TypeScript détecte le problème, et quoi modifier pendant une migration.

Quels inputs fournir à la skill

vue-jsx-best-practices donne de meilleurs résultats si vous fournissez du vrai code et du contexte, pas seulement « help with Vue JSX ». Incluez :

• le code source du composant
• s’il s’agit bien de Vue 3
• si vous utilisez JSX ou TSX
• les erreurs TypeScript actuelles, le cas échéant
• si le code vient de React
• votre outil de build, par exemple Vite

Input minimal utile :

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

Meilleur input :

• « 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. »

La règle clé que la skill vue-jsx-best-practices fait respecter

La conclusion pratique principale est simple :

• utilisez class, pas className
• utilisez for, pas htmlFor
• utilisez des noms d’attributs de style HTML, alignés sur les templates Vue
• utilisez des noms standards de gestionnaires d’événements avec le préfixe on, comme onClick

C’est important parce que le runtime Vue peut se montrer permissif, mais TypeScript devrait signaler les formes à la React. Et c’est une bonne chose : cela permet d’attraper les incohérences tôt.

Transformer un objectif flou en prompt solide

Prompt faible :

• « Fix this JSX. »

Prompt solide :

• « 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. »

Pourquoi c’est mieux :

• le prompt nomme explicitement l’origine du problème de migration
• il demande des remplacements concrets
• il distingue les problèmes de compilation de la permissivité du runtime
• il limite les conseils Vue trop génériques

Workflow recommandé pour les tâches de migration

Un bon workflow d’usage de vue-jsx-best-practices est le suivant :

1. Collez le composant React d’origine ou le composant JSX hybride.
2. Demandez une première passe de conversion vers les conventions Vue JSX.
3. Demandez une seconde passe centrée uniquement sur la compatibilité TypeScript.
4. Comparez props, labels et bindings d’événements ligne par ligne.
5. Lancez votre vérification de types en local et renvoyez à la skill les erreurs restantes.

Cette approche par étapes vaut mieux qu’une demande de « migration complète » en une seule fois, car cette skill est surtout forte sur le nettoyage des conventions JSX, pas sur une réécriture complète entre frameworks.

Ce qu’il faut vérifier dans le code converti

Après avoir utilisé vue-jsx-best-practices, inspectez :

• les labels utilisant for
• les bindings de classes CSS via class
• les noms de props DOM copiés depuis React
• l’orthographe des gestionnaires d’événements
• si le résultat suppose encore des patterns de composants React

La skill peut améliorer la syntaxe et les conventions, mais vous devez toujours valider la logique propre au framework, comme les hooks, l’état et les API de composants.

Points d’attention avec TypeScript et Vite

Le contenu source mentionne explicitement la configuration TypeScript pour l’inférence de types Vue JSX ainsi que la configuration Vite comme sujets pertinents. En pratique, cela veut dire qu’il ne faut pas traiter les erreurs d’attributs comme un simple sujet de style. Si votre configuration TSX est correcte, les attributs invalides au format React devraient remonter lors du typage. Si ce n’est pas le cas, vérifiez votre plugin Vue JSX et votre configuration TypeScript avant de faire confiance à un résultat qui « fonctionne » au runtime.

Cas d’usage idéaux et cas où la skill convient mal

Bon fit :

• migration React vers Vue en TSX
• revue de code sur les conventions Vue JSX
• correction d’erreurs d’attributs JSX dans Vue 3
• harmonisation du style d’équipe dans les render functions

Moins adapté :

• apprendre Vue depuis zéro
• aide sur la syntaxe des templates
• conception avec la Composition API
• débogage complet de setup build au-delà de la configuration liée au JSX

Exemple de demande qui produit de meilleurs résultats

Utilisez une formulation du type :

« 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. »

Ce prompt vous donne à la fois une correction et un modèle de revue réutilisable.

FAQ sur la skill vue-jsx-best-practices

vue-jsx-best-practices sert-elle uniquement aux migrations depuis React ?

Non. La migration depuis React est le cas d’usage le plus évident, mais la skill est aussi utile si votre équipe écrit directement en Vue TSX et veut des conventions cohérentes et sûres côté types. Elle aide dès que des noms d’attributs à la React se glissent dans du Vue JSX.

Est-ce que vue-jsx-best-practices installe un plugin ou modifie ma configuration ?

Non. La skill fournit un guidage ; ce n’est pas un package qui corrige automatiquement votre toolchain. Vous devez toujours disposer de votre propre configuration Vue JSX et TypeScript dans l’application. La skill vous aide à identifier à quoi le code devrait ressembler une fois cet environnement en place.

Quelle est la principale différence avec un prompt classique ?

Un prompt classique peut produire du JSX plausible sans respecter les conventions d’attributs propres à Vue. vue-jsx-best-practices est plus fiable sur ce problème précis, car elle place au centre le décalage Vue-vs-React en JSX et ses implications sur la sûreté de typage.

Cette skill est-elle adaptée aux débutants ?

Oui, à condition de connaître déjà un minimum Vue ou JSX. Son périmètre est assez étroit pour rester accessible. En revanche, si vous débutez totalement avec le rendu dans Vue, cette skill ne remplace pas une introduction plus large aux composants, aux templates ou aux render functions.

Quand ne faut-il pas utiliser vue-jsx-best-practices ?

Évitez-la si votre base de code utilise uniquement des templates Vue et pas de JSX/TSX. Évitez-la aussi si votre problème n’a rien à voir avec le nommage des attributs JSX, par exemple le routing, la gestion d’état ou le rendu serveur.

Le comportement runtime casse-t-il toujours si j’utilise des attributs à la React ?

Pas forcément. La référence indique que le runtime Vue peut être permissif et convertir correctement certains attributs. Le vrai enjeu, c’est surtout la cohérence et la sûreté de typage : TypeScript devrait rejeter ces conventions React dans du Vue JSX, ce qui est généralement exactement ce qu’on veut.

Comment améliorer l’usage de la skill vue-jsx-best-practices

Fournir ensemble le code, les erreurs et l’intention framework

Le moyen le plus rapide d’améliorer les résultats de vue-jsx-best-practices est de fournir :

• le composant source
• la forme cible attendue côté framework
• les vraies erreurs du compilateur ou de l’éditeur
• si l’objectif est une migration, un nettoyage ou une revue

Sans cela, la réponse risque de s’arrêter à des remplacements d’attributs évidents et de manquer des hypothèses JSX plus larges autour du composant.

Demander une revue orientée diff

Un prompt à forte valeur ajoutée est :

« 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. »

Cela limite la sur-édition et facilite la revue dans une base de code existante.

Séparer les corrections de syntaxe des réécritures framework

Un mode d’échec courant consiste à demander à la skill de gérer en même temps les différences de syntaxe JSX et toute la migration comportementale de React vers Vue. Pour améliorer la qualité du résultat, séparez ces tâches :

1. normaliser les conventions JSX
2. corriger les erreurs de type
3. refactorer la logique framework

Ainsi, vue-jsx-best-practices reste concentrée sur ce qu’elle couvre réellement le mieux.

Demander une checklist réutilisable

Le dépôt suggère déjà une logique de checklist de tâches. Vous pouvez aller plus loin en demandant à la skill de produire une liste d’audit prête pour l’équipe, par exemple :

• remplacer className par class
• remplacer htmlFor par for
• vérifier les gestionnaires d’événements on*
• relancer les vérifications TS sur les fichiers convertis

Cela transforme une aide ponctuelle en processus de revue reproductible.

Valider les hypothèses de configuration après la première passe

Si le résultat semble correct mais que votre éditeur ne signale pas les mauvais attributs, posez une question de suivi sur les hypothèses de l’environnement TSX. La skill fait référence à l’inférence TypeScript et à la configuration Vite comme éléments de contexte importants ; une validation trop faible dans votre setup local peut donc masquer de vraies erreurs.

Modes d’échec fréquents à surveiller

Après utilisation de vue-jsx-best-practices, surveillez en particulier :

• des noms d’attributs React encore présents dans des éléments imbriqués
• un résultat qui « fonctionne » au runtime mais échoue aux vérifications TS
• des conseils de migration qui modifient le comportement, pas seulement la syntaxe
• un nettoyage incomplet des labels, classes et props DOM

Ce sont de très bons candidats pour une seconde passe de revue.

Améliorer le prompt après la première réponse

Un bon prompt d’itération est :

« 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. »

Ce suivi est souvent plus efficace que de demander une réécriture entièrement nouvelle.

Utiliser le fichier de référence comme point d’ancrage pour décider

Si vous hésitez à faire confiance au résultat, comparez-le à :

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

Ce fichier est le point d’ancrage le plus clair pour comprendre le comportement attendu de cette skill. Pour décider de l’installation, c’est aussi un bon signal : la skill est compacte, mais son guidage est assez précis pour réduire les erreurs Vue JSX les plus évitables.