La Composition API a résolu un vrai problème de l'Options API : la logique liée à une même fonctionnalité (pagination, filtre, souscription à un WebSocket) n'est plus éclatée entre data, computed, methods et watch. Mais cette liberté a un revers : sans discipline, les composables deviennent une nouvelle façon de créer du couplage caché, de l'état partagé par accident, ou des fuites mémoire via des écouteurs jamais nettoyés. Ce billet détaille comment structurer des composables qui restent prévisibles à grande échelle.
Le problème : état partagé involontairement entre instances
L'erreur la plus fréquente avec un premier composable est de créer l'état réactif à l'extérieur de la fonction composable, au niveau du module.
// useCounter.js - BUG : l'état est partagé entre tous les composants qui appellent useCounter()
import { ref } from 'vue';
const count = ref(0); // créé une seule fois, au chargement du module
export function useCounter() {
function increment() {
count.value++;
}
return { count, increment };
}
Deux composants indépendants qui appellent useCounter() se retrouvent à partager le même count, parce que ref(0) n'est exécuté qu'une seule fois, à l'import du module. Incrémenter le compteur dans un composant fait bouger l'affichage dans l'autre, sans qu'aucun des deux composants n'ait de raison de le soupçonner.
Pourquoi ça arrive : confondre singleton de module et état par instance
C'est exactement le même mécanisme qui rend les composables puissants pour l'état global intentionnel (un store d'authentification partagé par toute l'application) et dangereux pour l'état qu'on croit local à chaque composant. La frontière entre les deux n'est pas visible dans la syntaxe : useCounter() et useAuth() s'appellent de la même façon, mais l'un doit créer un nouvel état à chaque appel, l'autre doit réutiliser le même.
Diagnostiquer : vérifier où vit le ref
La règle de diagnostic est simple à vérifier dans le code : si le ref ou le reactive est déclaré à l'intérieur de la fonction composable, chaque appel crée une instance indépendante. S'il est déclaré à l'extérieur, au niveau module, il est partagé par tous les appelants.
// useCounter.js - correction : l'état vit à l'intérieur de la fonction composable
import { ref } from 'vue';
export function useCounter(initialValue = 0) {
const count = ref(initialValue); // créé à chaque appel de useCounter()
function increment() {
count.value++;
}
return { count, increment };
}
Pour l'état réellement global et volontaire, le pattern inverse - état au niveau module - est le bon, mais il doit être explicite et documenté comme tel, idéalement en gardant le composable au singulier conceptuel ("il n'existe qu'un seul useAuthStore").
La correction : composables avec cycle de vie et nettoyage explicite
Nettoyer systématiquement les effets de bord
Un composable qui souscrit à un événement, un WebSocket, ou un setInterval doit nettoyer cette souscription dans onUnmounted, sinon chaque montage/démontage du composant accumule des écouteurs fantômes qui continuent de tourner en arrière-plan.
// useWindowSize.js
import { ref, onMounted, onUnmounted } from 'vue';
export function useWindowSize() {
const width = ref(window.innerWidth);
const height = ref(window.innerHeight);
function handleResize() {
width.value = window.innerWidth;
height.value = window.innerHeight;
}
onMounted(() => window.addEventListener('resize', handleResize));
onUnmounted(() => window.removeEventListener('resize', handleResize));
return { width, height };
}
Le piège classique sur ce pattern : appeler un composable conditionnellement (dans un if, après un montage asynchrone) casse les hooks de cycle de vie, parce que Vue associe onMounted/onUnmounted à l'instance de composant active au moment de l'appel. Les composables doivent être appelés en haut de setup() ou de <script setup>, jamais dans une branche conditionnelle ou après un await.
<script setup>
// INCORRECT : après un await, l'instance de composant active a été perdue
async function setup() {
await someAsyncCheck();
const { width } = useWindowSize(); // onMounted ne s'attachera à rien
}
</script>
Exposer une API cohérente avec des readonly quand c'est pertinent
Un composable qui expose un état interne en lecture-écriture sans intention explicite invite les composants consommateurs à le muter directement, ce qui recrée la même traçabilité floue que des variables globales mutables.
// usePagination.js
import { ref, computed, readonly } from 'vue';
export function usePagination(totalItems, pageSize = 20) {
const currentPage = ref(1);
const totalPages = computed(() => Math.ceil(totalItems.value / pageSize));
function goToPage(page) {
if (page < 1 || page > totalPages.value) return;
currentPage.value = page;
}
return {
currentPage: readonly(currentPage), // lecture seule pour les consommateurs
totalPages,
goToPage, // seule façon autorisée de modifier currentPage
};
}
readonly force les consommateurs à passer par goToPage, ce qui centralise la validation (page hors limites, par exemple) à un seul endroit plutôt que de la dupliquer dans chaque composant qui manipule currentPage directement.
Composer plusieurs composables sans créer de dépendances cachées
Un composable qui appelle un autre composable fonctionne bien tant que la dépendance est explicite dans les paramètres. Le piège est de rendre un composable dépendant d'un état global injecté implicitement (via inject() sans valeur par défaut claire), ce qui rend les tests unitaires impossibles sans reconstituer tout l'arbre de providers.
// useCart.js - dépendance explicite plutôt qu'injection implicite
import { ref, computed } from 'vue';
export function useCart(pricingService) {
const items = ref([]);
const total = computed(() =>
items.value.reduce((sum, item) => sum + pricingService.getPrice(item), 0)
);
function addItem(item) {
items.value.push(item);
}
return { items, total, addItem };
}
// useCart.test.js - pricingService est un simple mock, pas de provider Vue à monter
import { useCart } from './useCart';
test('calcule le total avec le service de prix fourni', () => {
const mockPricingService = { getPrice: (item) => item.price * item.qty };
const { items, total, addItem } = useCart(mockPricingService);
addItem({ price: 10, qty: 2 });
expect(total.value).toBe(20);
});
Les compromis
Forcer l'injection de dépendances explicite dans chaque composable rend parfois la signature verbeuse pour des cas simples, et peut sembler excessif pour un composable trivial sans dépendance externe. La règle pragmatique : explicite par défaut dès qu'il y a une dépendance testable (service HTTP, service de prix, horloge pour les tests temporels), inject() acceptable pour de la configuration vraiment transverse (thème, locale) qui ne change jamais le comportement testé unitairement.
readonly a un coût de performance marginal (il enveloppe la valeur dans un proxy supplémentaire) qui est négligeable dans l'immense majorité des cas, mais peut devenir mesurable sur des structures de données très volumineuses mises à jour à haute fréquence (un flux temps réel avec des milliers de mises à jour par seconde).
Quand le composable ne suffit plus
Pour un état partagé entre des composants qui n'ont pas de lien parent-enfant direct et qui doit persister au-delà du cycle de vie d'un composant individuel (panier d'achat, session utilisateur), un composable avec état au niveau module fonctionne pour des besoins simples, mais une bibliothèque de gestion d'état dédiée (Pinia) devient préférable dès que la logique inclut de la persistance, du undo/redo, ou des outils de debug (Vue Devtools affiche nativement les stores Pinia, pas un état arbitraire caché dans un module).
Le point à retenir : un composable Vue 3 n'est prévisible que si on sait, en le lisant, si son état est recréé à chaque appel ou partagé globalement, et si ses effets de bord sont nettoyés de façon déterministe. Ces deux garanties, pas la syntaxe de la Composition API elle-même, sont ce qui fait la différence entre une logique réutilisable et une source de bugs difficiles à tracer.
