Composition API vs Options API de Vue 3 pour les grandes bibliothèques de composants
Composition API vs Options API de Vue 3 : comment chaque approche influence la réutilisation, les tests et l'intégration des contributeurs dans de grandes bibliothèques de composants d'administration.

Pourquoi ce choix compte dans de grandes bibliothèques de composants d'administration
Une grande bibliothèque de composants dans une application d'administration n'est pas un site marketing avec quelques boutons. Ce sont des dizaines (ou centaines) de blocs réutilisables qui reviennent sur plusieurs écrans : tableaux de données avec tri et actions en masse, panneaux de filtres, formulaires avec règles de validation, tiroirs et modales, flux de confirmation, et de petits utilitaires comme sélecteurs de date et gardes de permissions.
Parce que ces patterns apparaissent partout, les équipes copient souvent du code et le modifient pour respecter les délais. Un tableau obtient une barre de filtre personnalisée, un autre une version légèrement différente, et bientôt vous avez cinq versions « presque identiques ». C'est là que la question Composition API vs Options API cesse d'être une préférence personnelle et commence à affecter la santé de toute la bibliothèque.
Ce qui casse d'abord, en général, c'est la cohérence. L'interface fonctionne encore, mais le comportement diverge : une modale se ferme sur Échap à un endroit et pas à un autre ; un même champ valide au blur sur une page et au submit sur une autre. Après ça, la vitesse diminue parce que chaque changement nécessite de chasser des quasi-duplications. Enfin, la confiance baisse : on évite les refactors parce qu'on ne peut pas prévoir l'impact.
Trois décisions pratiques importent le plus dans une bibliothèque partagée :
- Réutilisation du code : comment emballer la logique partagée sans dépendances emmêlées.
- Tests : à quel point il est facile de vérifier le comportement sans tests fragiles axés sur l'UI.
- Onboarding : à quelle vitesse un nouveau contributeur peut lire un composant et faire un changement en toute sécurité.
Un exemple simple : votre admin a 20 pages de liste, et le produit demande une nouvelle fonctionnalité « Filtres sauvegardés ». Si la logique du tableau, des filtres et de la synchronisation d'URL est éparpillée et incohérente, vous livrerez soit lentement soit avec des bugs. Le style d'API que vous choisissez façonne si cette logique vit en un endroit réutilisable, à quel point elle est clairement raccordée à chaque écran et à quel point il est facile pour un nouveau venu de l'étendre.
Si vous construisez des apps d'administration en Vue 3 (y compris des équipes qui utilisent Vue 3 dans des plateformes comme AppMaster pour la couche UI web), prendre cette décision tôt peut vous économiser des mois de maintenance plus tard.
Comment Options et Composition diffèrent dans le code au quotidien
La façon la plus rapide de sentir la différence est d'ouvrir un gros composant d'administration et de se demander : « Où je change le comportement pour cette fonctionnalité ? » Dans une bibliothèque de composants, cette question revient tous les jours.
Avec l'Options API, le code est groupé par type : data pour l'état, methods pour les actions, computed pour les valeurs dérivées, et watch pour les effets de bord. Cette structure est facile à scanner quand un composant est petit. Dans un grand tableau ou formulaire, la logique d'une seule fonctionnalité (comme les actions en masse ou la validation d'un champ) finit souvent dispersée dans plusieurs blocs. On peut garder ça propre, mais il faut de la discipline et une nomenclature cohérente pour éviter de sauter partout dans le fichier.
Avec la Composition API, le code est généralement groupé par fonctionnalité. Vous définissez l'état lié, les valeurs dérivées, les effets de bord et les helpers côte à côte, et vous pouvez extraire la logique répétée dans des composables. Dans une bibliothèque de type admin, cela correspond souvent à la pensée des gens : « tout ce qui concerne le filtrage est ici », « tout ce qui concerne la sélection de ligne est ici ». Cela peut aussi réduire la duplication entre composants similaires, comme réutiliser un composable usePagination à travers plusieurs tableaux.
Une grande différence quotidienne est la façon dont les dépendances apparaissent.
- L'Options API peut sembler plus implicite : une méthode peut dépendre de
this.user,this.filtersetthis.loading, et vous ne le découvrez qu'en lisant l'intérieur de la méthode. - La Composition API tend à être plus explicite : quand une fonction ferme sur
filtersetloading, vous voyez ces variables définies à proximité, et vous pouvez les passer aux helpers quand nécessaire.
Le compromis est que la Composition API peut devenir bruyante si tout est déversé dans un seul setup() sans structure.
Règle pratique :
- Choisissez Options API quand les composants sont surtout présentiels et ont une logique légère.
- Choisissez Composition API quand les composants ont plusieurs fonctionnalités avec des règles partagées à travers la bibliothèque.
- Si vous choisissez Composition API, mettez-vous d'accord sur une mise en page simple qui groupe le code par fonctionnalité (pas « tous les refs d'abord »).
- Si vous choisissez Options API, imposez une nomenclature et gardez la logique liée ensemble avec de courts commentaires et des noms de méthodes cohérents.
Les deux peuvent fonctionner. L'essentiel est de choisir le style d'organisation qui rend la prochaine modification évidente, pas astucieuse.
Réutilisation du code : ce qui évolue proprement et ce qui devient chaotique
Dans les apps de type admin, la réutilisation n'est pas un luxe. Vous répétez les mêmes comportements sur des dizaines d'écrans, et de petites incohérences se transforment en bugs et tickets support.
La plupart des besoins de réutilisation tombent dans quelques catégories récurrentes : tri/filtrage/pagination qui correspondent au backend, validation de formulaires et mapping d'erreurs, contrôles de permissions et affichage conditionnel, synchronisation de requêtes (params d'URL, vues sauvegardées, filtres par défaut), et actions en masse avec règles de sélection dans les tableaux.
Réutilisation avec Options API : puissante, mais facile à rendre opaque
Avec l'Options API, la réutilisation commence souvent par des mixins, des extends ou des plugins.
Les mixins sont rapides, mais ils évoluent mal car ils cachent d'où vient une méthode ou une valeur calculée. Deux mixins peuvent entrer en collision sur un même nom de méthode, et vous voilà en train de déboguer un comportement qui n'est pas visible dans le fichier du composant.
extends peut sembler plus propre que les mixins, mais crée des puzzles d'héritage où il faut lire plusieurs fichiers pour comprendre ce que fait réellement un composant. Les plugins fonctionnent bien pour les préoccupations au niveau app (directives globales, services partagés), mais ce ne sont pas un bon endroit pour des règles métier qui varient selon l'écran.
Le moment gênant arrive généralement quand la réutilisation devient implicite. Les nouveaux contributeurs ne peuvent pas répondre à « d'où viennent ces données ? » sans chercher dans tout le code.
Réutilisation avec Composition API : des composables qui restent explicites
La réutilisation en Composition API s'appuie généralement sur des composables : petites fonctions qui retournent des refs, des valeurs calculées et des handlers. Le grand avantage est que la réutilisation devient visible près du haut du composant, et vous pouvez passer des paramètres au lieu de compter sur un contexte de composant caché.
Par exemple, un composable usePagination peut accepter des valeurs par défaut et émettre des changements dans une forme consistante, tandis que usePermissions peut accepter le rôle courant et un nom de fonctionnalité. À ce stade, le choix devient moins syntaxe et plus préférence pour un câblage explicite plutôt qu'un héritage implicite.
Pour garder la réutilisation prédictible, traitez chaque unité réutilisable comme une petite API : donnez-lui un nom clair, définissez entrées et sorties, et une seule responsabilité. Si un composable commence à gérer pagination, cache, permissions et notifications, scindez-le. Il est beaucoup plus facile de remplacer une pièce plus tard sans tout casser.
Construire des formulaires et tableaux réutilisables sans douleur
Dans les apps de type admin, les formulaires et tableaux sont l'endroit où une bibliothèque paie ou devient un labyrinthe. Les deux APIs peuvent marcher. La différence est la façon de packager le comportement partagé comme l'état dirty, le mapping d'erreurs et les flux de soumission sans rendre chaque composant « spécial ».
Pour la logique partagée des formulaires, l'Options API vous pousse souvent vers des mixins ou des helpers partagés. Les mixins semblent pratiques au début, mais plus tard il devient difficile de répondre à des questions basiques : « D'où vient cette erreur de champ ? » ou « Pourquoi le submit est désactivé ? »
La Composition API rend ce type de réutilisation plus visible parce que vous pouvez déplacer la logique dans des composables (par exemple useDirtyState, useFormErrors, useSubmitFlow) et voir exactement ce que tire un composant de formulaire. Dans une grande bibliothèque, cette clarté compte souvent plus que d'économiser quelques lignes.
Une façon pratique de garder les APIs de composants stables est de traiter votre surface publique comme un contrat : props, emits et slots doivent changer rarement, même si vous réécrivez l'intérieur. Ce contrat ressemble aux deux styles, mais la Composition API rend souvent les refactors plus sûrs car vous pouvez remplacer un composable à la fois sans toucher à l'API du template.
Patterns qui restent raisonnables à mesure que la bibliothèque grandit :
- Construire des composants de base qui font bien un travail (BaseInput, BaseSelect, BaseTable), puis les composer en composants de fonctionnalité.
- Préférer les slots pour la flexibilité de mise en page (zone d'actions, états vides, rendu de cellules) plutôt que d'ajouter des props pour chaque cas particulier.
- Normaliser tôt les événements (par exemple
update:modelValue,submit,rowClick) pour que les apps ne dépendent pas des détails internes. - Garder la validation et le formatage proches des inputs, mais laisser les règles métier à l'extérieur (dans des composables ou des conteneurs parents).
L'over-abstraction est le piège courant. Un « super formulaire » qui gère tous les types de champs, toutes les règles de validation et toutes les options de layout devient souvent plus dur à utiliser que du Vue simple. Une bonne règle : si un composant de base nécessite plus qu'une poignée de props pour couvrir les besoins de toutes les équipes, il vaut probablement mieux le diviser en deux composants.
Parfois la duplication est le choix juste. Si une seule page a besoin d'un en-tête de tableau étrange avec groupement multi-lignes, copiez un petit morceau et gardez-le local. Les abstractions astucieuses ont une longue queue de maintenance, surtout quand de nouveaux contributeurs essaient de comprendre la différence entre composants « normaux » et un framework dans le framework.
Si vous décidez entre Composition et Options pour une grande bibliothèque de formulaires et tableaux, optimisez d'abord la lisibilité du flux de données. La réutilisation est bonne, mais pas lorsqu'elle cache le chemin de l'action utilisateur à l'événement émis.
Impact sur les tests : ce qui devient plus facile à vérifier
Dans une bibliothèque de composants, les tests se répartissent généralement en trois catégories : logique pure (formatage, validation, filtrage), rendu (ce qui apparaît pour un état donné), et interactions (clics, saisie, clavier, émissions). Le style d'API choisit change la fréquence à laquelle vous pouvez tester la première catégorie sans monter un composant complet.
Les tests avec Options API ressemblent souvent à « montez le composant, touchez l'état de l'instance, assert sur le DOM ». Ça marche, mais cela encourage des tests plus larges parce que la logique est mélangée dans methods, computed, watch et hooks de cycle de vie. Quand quelque chose échoue, vous passez aussi du temps à déterminer si c'est un problème de timing du watcher, d'un effet de cycle de vie, ou de la logique elle-même.
L'Options API est souvent pratique pour :
- Les flux utilisateurs dépendant de l'ordre du cycle de vie (fetch au mount, reset au changement de route)
- Les comportements pilotés par watchers (auto-save, synchronisation de requête)
- L'émission d'événements à partir de méthodes du composant (
save(),reset(),applyFilter())
La Composition API déplace l'équilibre. Si vous déplacez la logique dans des composables, vous pouvez unit tester cette logique comme des fonctions pures, avec de petites entrées et des sorties claires. Cela réduit le nombre de tests « monter et cliquer » nécessaires, et rend les échecs plus locaux. Cela facilite aussi le contrôle des dépendances : au lieu de mocker un global, vous passez une dépendance (fonction fetch, formateur de date, vérificateur de permissions) dans le composable.
Exemple concret : un AdminTable réutilisable avec tri, pagination et lignes sélectionnées. Avec Composition API, la logique de sélection peut vivre dans useRowSelection() et être testée sans rendre le tableau du tout (basculer, effacer, sélectionner tout, préserver entre pages). Ensuite, gardez un petit ensemble de tests de composants pour confirmer que le template relie bien les boutons, checkboxes et events émis.
Pour garder les tests petits et lisibles (quel que soit le style) :
- Mettez les règles métier dans des fonctions pures ou des composables, pas dans des watchers.
- Cachez les effets de bord (fetch, storage, timers) derrière des dépendances injectées.
- Préférez quelques tests d'intégration ciblés par composant, pas un seul test gigantesque « tout en un ».
- Nommez états et événements de façon cohérente dans la bibliothèque (ça réduit la configuration des tests).
- Évitez les couplages cachés (par exemple méthode A qui dépend que le watcher B se déclenche).
Si votre objectif est une décision de style qui améliore la stabilité des tests, poussez vers moins de comportements pilotés par le cycle de vie et plus d'unités logiques isolées que vous pouvez vérifier sans le DOM.
Onboarding des nouveaux contributeurs : à quelle vitesse les gens deviennent productifs
Dans une grande bibliothèque de composants d'administration, l'onboarding porte moins sur l'apprentissage de Vue que sur trouver les choses, suivre les conventions et se sentir en sécurité pour modifier. Les principaux ralentissements viennent de trois lacunes : navigation (où est la logique ?), conventions (comment fait-on ici ?) et confiance (comment changer sans casser cinq écrans ?).
Avec l'Options API, les nouveaux avancent souvent plus vite le premier jour parce que la structure est familière : props, data, computed, methods, watchers. Le compromis est que le comportement réel est souvent dispersé. Une fonctionnalité comme « filtrage côté serveur » peut être répartie entre un watcher, un computed, deux méthodes et un mixin. Les gens lisent chaque bloc, mais passent du temps à assembler l'histoire.
Avec la Composition API, l'avantage d'onboarding est que la logique liée peut rester ensemble : état, effets de bord et helpers au même endroit. Le coût est l'apprentissage des composables. Les nouveaux doivent comprendre des patterns comme useTableState() et comment les valeurs réactives traversent plusieurs composables. Sans frontières claires, cela peut donner l'impression de sauter entre des fichiers sans carte.
Quelques conventions qui répondent à la plupart des questions, quel que soit le style :
- Utilisez une structure prévisible :
components/,composables/,types/,tests/. - Choisissez un pattern de nommage et respectez-le (par exemple :
useX,XTable,XForm). - Ajoutez de courts docblocks : ce que fait le composant, props clés et événements principaux.
- Définissez une règle « passe-partout » : quand est-il acceptable d'ajouter un nouveau composable ou helper.
- Gardez un petit composant « golden » qui montre le pattern préféré.
Exemple : si votre équipe génère un panneau admin Vue 3 puis le personnalise (par exemple une app web construite sur AppMaster et étendue), l'onboarding s'améliore beaucoup quand il y a un endroit évident pour ajuster le comportement des tableaux (tri, filtres, pagination) et un endroit évident pour ajuster le câblage UI (slots, renderers de colonne, actions de ligne). Cette clarté importe plus que l'API choisie.
Étapes pas à pas : choisir un style et l'introduire en sécurité
Pour une grande UI d'administration, la façon la plus sûre de trancher est de démarrer avec une fonctionnalité bien délimitée et de la traiter comme pilote, pas comme un refactor global.
Choisissez un module avec un comportement clair et beaucoup de réutilisation, comme le filtrage des tableaux ou la validation des formulaires. Avant de toucher au code, notez ce qu'il fait aujourd'hui : entrées (props, params d'URL, actions utilisateur), sorties (événements, émissions, changements d'URL) et cas limites (état vide, reset, erreurs serveur).
Ensuite, fixez des limites. Décidez ce qui doit rester dans le composant (rendu, événements DOM, accessibilité) et ce qui peut bouger vers du code partagé (parsing des filtres, debounce, construction des params API, état par défaut). C'est là que les bibliothèques se trompent souvent : si vous déplacez des décisions UI dans du code partagé, vous rendez la réutilisation plus difficile.
Plan de déploiement pratique :
- Choisissez un composant qui montre clairement le pattern et qui est utilisé par plusieurs écrans.
- Extraites une unité partagée (un composable ou un helper simple) avec une API petite et explicite.
- Ajoutez un test ciblé pour cette unité, basé sur des scénarios réels d'admin.
- Refactorez le composant choisi de bout en bout en utilisant la nouvelle unité.
- Appliquez le même pattern à un autre composant pour confirmer qu'il scale.
Gardez l'API partagée ennuyeuse et évidente. Par exemple, un composable useTableFilters() pourrait accepter des filtres initiaux et exposer filters, apply(), reset() et une fonction toRequestParams(). Évitez la « magie » qui lit l'état global, sauf si c'est déjà une règle ferme dans votre app.
Après le pilote, publiez une courte consigne interne avec un exemple que les contributeurs peuvent copier. Une règle concrète bat un long document, par exemple : « Toute la logique de filtrage des tables vit dans un composable ; les composants ne lient que les contrôles UI et appellent apply() ».
Avant d'étendre l'approche, utilisez une définition simple de fait :
- Le nouveau code se lit de la même façon sur deux composants différents.
- Les tests couvrent la logique partagée sans monter l'UI complète.
- Un nouveau contributeur peut changer une règle de filtre sans toucher des fichiers non liés.
Si votre équipe construit aussi des portails admin avec un outil no-code comme AppMaster, la même mentalité de pilote aide : choisissez un workflow (par ex. approbations), définissez le comportement, standardisez le pattern avant de le répliquer.
Erreurs courantes et pièges dans les grandes bibliothèques
Les plus gros problèmes dans une grande bibliothèque ne portent généralement pas sur la syntaxe. Ils viennent d'une accumulation de petites décisions locales qui rendent la réutilisation, les tests et la maintenance plus difficiles.
Un piège courant est de mélanger les patterns au hasard. Si la moitié de la bibliothèque utilise l'Options API et l'autre moitié la Composition API sans règle, chaque nouveau composant devient un débat de style. Vous vous retrouvez aussi avec des solutions dupliquées aux mêmes problèmes (formulaires, tableaux, permissions) écrites différemment. Si vous autorisez les deux, écrivez une politique claire : le nouveau code utilise un style, l'ancien n'est touché qu'en cas de besoin, et la logique partagée vit à un endroit convenu.
Un autre piège est le « god composable ». Il commence souvent comme un useAdminPage() ou useTable() utile et absorbe routing, fetching, cache, sélection, dialogues, toasts et permissions. Il devient difficile à tester parce qu'un appel déclenche beaucoup d'effets de bord. Il devient aussi difficile à réutiliser parce que chaque écran n'a besoin que de 30% mais subit la complexité de 100%.
Les watchers sont une autre source de douleurs. Ils sont faciles à ajouter quand quelque chose semble désynchronisé, mais les bugs de timing apparaissent plus tard (surtout avec des données asynchrones et des inputs debouncés). Quand on signale « ça efface parfois ma sélection », vous pouvez passer des heures à reproduire le problème.
Signaux d'alerte :
- Un composant ne fonctionne que si utilisé dans un ordre exact de props et d'événements.
- Un composable lit/écrit l'état global sans le rendre évident.
- Plusieurs watchers mettent à jour la même portion d'état.
- Les refactors cassent régulièrement des écrans consommateurs.
- Les contributeurs évitent de toucher « ce fichier » parce qu'il est risqué.
Le dernier piège est de casser l'API publique lors des refactors. Dans les apps d'administration, des composants comme tableaux, filtres et champs se répandent vite. Renommer une prop, changer un événement émis ou modifier le comportement d'un slot peut casser silencieusement des dizaines d'écrans.
Une approche plus sûre est de traiter les APIs de composants comme des contrats : dépréciez au lieu de supprimer, gardez des shims de compatibilité pendant un temps, et ajoutez des tests d'usage simples qui montent le composant comme les consommateurs le font. Si vous générez des interfaces admin Vue 3 avec des outils comme AppMaster, cela compte d'autant plus : des contrats de composants stables facilitent la réutilisation d'écrans et rendent les changements prévisibles.
Vérifications rapides avant de vous engager dans un pattern
Avant de choisir Composition API, Options API ou un mixte, faites quelques contrôles rapides sur des composants réels de votre bibliothèque. Le but est simple : rendre facile la recherche de la logique, la réutiliser en sécurité et tester les parties dont les admins dépendent.
1) Peut-on trouver la logique rapidement ?
Ouvrez un composant type admin (filtres + tableau + permissions + actions en masse). Faites comme si vous étiez nouveau dans le code.
Un bon signe : un contributeur peut répondre « où est la logique de filtrage ? » ou « qu'est-ce qui désactive ce bouton ? » en moins de 2 minutes. Avec Options API, cela veut dire que la logique est clairement séparée en computed, methods et watchers. Avec Composition API, cela veut dire que setup() est organisé en petits blocs nommés (ou composables) et évite une seule grosse fonction.
2) Les utilitaires partagés se comportent-ils comme des fonctions, pas comme de la magie ?
Quel que soit le pattern, le code partagé doit avoir des entrées et sorties claires et peu d'effets de bord. Si un helper fouille l'état global, mutile des objets passés ou déclenche des appels réseau sans que ce soit évident, la réutilisation devient risquée.
Contrôles rapides :
- Peut-on lire la signature d'un composable/helper et deviner ce qu'il retourne ?
- Peut-on l'utiliser dans deux composants sans configuration cachée ?
- Peut-on réinitialiser son état dans les tests sans astuces ?
3) Vos tests ciblent-ils les comportements d'admin ?
Les apps d'admin échouent de façon prédictible : filtres erronés, permissions qui laissent passer des actions, formulaires qui valident de façon inconsistante, état de tableau qui casse après des éditions.
Au lieu de tester des détails d'implémentation (watchers vs refs), écrivez des tests autour du comportement : « donné le rôle X, l'action Y est cachée », « la sauvegarde affiche une erreur et conserve la saisie », « le changement de filtre met à jour la requête et le message d'état vide ». Cela rend les tests stables même si vous refactorez entre styles.
4) Avez-vous une norme pour l'état asynchrone ?
Les grandes bibliothèques accumulent beaucoup de petits flux asynchrones : charger des options, valider des champs, fetcher des lignes de tableau, retry sur erreur. Si chaque composant invente son loading/error, l'onboarding et le debug deviennent lents.
Choisissez une forme claire pour l'état asynchrone (loading, error, retries, annulation). La Composition API encourage souvent un composable réutilisable useAsyncX(), tandis que l'Options API peut standardiser un état data() avec des méthodes partagées. Les deux marchent si la forme est cohérente.
5) Les APIs publiques des composants sont-elles stables et auto-explicatives ?
Traitez les composants comme des produits. Leurs props, events émis et slots sont le contrat. Si ce contrat change souvent, chaque écran admin devient fragile.
Cherchez des commentaires qui expliquent l'intention (pas les mécaniques) : que signifient les props, quels événements sont garantis, et ce qui est considéré interne. Si vous construisez des outils admin avec une plateforme comme AppMaster, cette même approche aide : des blocs stables accélèrent la création d'écrans futurs.
Scénario d'exemple et prochaines étapes pour votre équipe
Imaginez une page « Users » à reconstruire : barre de filtres (statut, rôle, date de création), tableau avec lignes sélectionnables, actions en masse (désactiver, supprimer, exporter) et contrôle par rôle (seuls les admins peuvent supprimer en masse, les managers peuvent éditer les rôles).
Avec Composition API vs Options API, l'UI peut être identique, mais le code s'organise différemment.
En Options API, vous finissez souvent avec un gros composant qui contient data pour filtres et sélection, computed pour l'état dérivé, et methods pour fetch, actions en masse et vérifications de permissions. La réutilisation apparaît via mixins ou helpers partagés. C'est familier, mais la logique liée peut devenir dispersée (fetch dans methods, sync d'URL dans des watchers, permissions dans computed).
En Composition API, vous découpez généralement la page en composables ciblés : un pour la query et les filtres, un pour la sélection et les actions en masse, un pour les permissions. Le composant page assemble ces pièces, et la logique de chaque préoccupation reste ensemble. Le compromis : il faut des noms et des conventions de dossiers clairs pour que les contributeurs n'aient pas l'impression que tout est « magique dans setup ».
La réutilisation apparaît naturellement autour des filtres synchronisés à l'URL, des patterns serveur pour tableaux (pagination, tri, select-all, guards pour actions en masse), des vérifications de permissions et des états vide/chargement cohérents.
Plan d'étapes suivant qui marche pour la plupart des équipes :
- Choisissez un style par défaut pour le nouveau code et autorisez les exceptions seulement avec une raison écrite.
- Définissez des conventions : où vivent les composables, comment les nommer, ce qu'ils peuvent importer et ce qu'ils doivent retourner.
- Ajoutez une page de référence (comme cette page Users) comme standard d'or pour les patterns et la structure.
- Écrivez des tests autour des parties réutilisables d'abord (filtres, permissions, actions en masse), pas le layout visuel.
- Si la rapidité prime sur la personnalisation profonde pour certains écrans, envisagez de générer ces écrans avec un outil no-code comme AppMaster, et concentrez votre bibliothèque manuelle sur les parties vraiment uniques.
Si vous utilisez déjà AppMaster, il aide à garder la même mentalité entre parties générées et écrites à la main : contrats de composants stables et logique partagée empaquetée en petites unités explicites. Pour les équipes qui évaluent du no-code pour des outils internes, AppMaster (appmaster.io) est conçu pour générer des applications complètes (backend, web et mobile) tout en vous permettant de standardiser une UI Vue 3 quand cela compte.
Si vous ne faites qu'une chose cette semaine, faites de la page Users votre template et faites-en respecter le pattern dans les revues de code. Un exemple clair vaut mieux qu'un long guide de style.
FAQ
Par défaut, privilégiez la Composition API si votre bibliothèque répète des comportements comme filtres, pagination, actions en masse et contrôle par permissions. Elle facilite l'extraction de la logique partagée en composables et rend les dépendances plus explicites. Utilisez l'Options API lorsque les composants sont surtout présentiels et ont peu de logique.
L'Options API regroupe le code par type (data, methods, computed, watch), donc la logique d'une même fonctionnalité finit souvent dispersée. La Composition API regroupe plutôt par fonctionnalité, permettant de rassembler tout ce qui concerne les « filtres » ou la « sélection » au même endroit. Le meilleur choix est celui qui rend la prochaine modification facile à trouver et sûre à appliquer.
Avec l'Options API, la réutilisation commence souvent par des mixins ou extends, qui peuvent masquer l'origine d'une méthode ou d'une valeur calculée et provoquer des collisions de noms. Avec la Composition API, la réutilisation se fait généralement via des composables avec des entrées et sorties claires, rendant le raccordement visible dans le composant. Pour une bibliothèque partagée, la réutilisation explicite reste maintenable plus longtemps.
Traitez chaque composable comme une petite API : une seule responsabilité, paramètres clairs et retours prévisibles. Si un composable commence à mélanger pagination, cache, permissions et notifications, scindez-le. Garder les composables petits facilite les tests, la réutilisation et réduit les effets de bord inattendus.
Gardez le contrat public stable : props, événements émis et slots doivent changer rarement. Placez le formatage et la validation basique près des champs, mais mettez les règles métier dans des composables ou des conteneurs. Ainsi, vous pouvez refactorer les internals sans forcer chaque écran à changer.
La Composition API facilite généralement les tests unitaires de la logique sans monter un composant complet, car vous pouvez tester directement des composables et des fonctions pures. L'Options API tend à pousser vers des tests montés où les watchers et l'ordre de cycle de vie ajoutent du bruit. Quel que soit le style, séparer les règles métier du câblage UI rend les tests plus petits et stables.
Standardisez une forme unique pour l'état asynchrone, par exemple loading, error, et un moyen clair de retry ou d'annulation. Ne laissez pas chaque composant inventer sa propre convention, car le debug devient lent et incohérent. Vous pouvez implémenter cette norme avec l'une ou l'autre API, l'important est la cohérence à travers la bibliothèque.
L'Options API est souvent plus simple le premier jour parce que la structure est familière : props, data, computed, methods, watchers. Mais la logique peut être dispersée. La Composition API devient plus rapide une fois que les gens connaissent vos composables et conventions de dossiers, car le comportement apparent est regroupé et la réutilisation est visible. L'onboarding s'améliore le plus avec un exemple « golden » et des revues de code qui appliquent les mêmes patterns.
Choisissez un module bien délimité et à forte réutilisation (par exemple le filtrage des tables) et traitez-le comme un pilote. Extraites une unité partagée avec une API petite et explicite, écrivez un test ciblé pour elle, puis refactorez un composant de bout en bout. Après validation sur au moins deux composants, étendez le pattern.
Signes avant-coureurs : des duplications proches dispersées, des chaînes de watchers qui se contredisent, des composants ne fonctionnant que dans un ordre exact de props/événements, et des changements fréquents qui cassent les props ou events. Si les contributeurs évitent certains fichiers car ils sont risqués, la bibliothèque a besoin de contrats plus clairs et d'une réutilisation explicite.


