Vue 3 et la Composition API : le guide complet

Sommaire

• Pourquoi Vue 3 aujourd’hui
• Ce que ce parcours vous permettra de faire
• Le parcours d’apprentissage
• Les concepts fondamentaux
• Options API et Composition API
• Vue d’ensemble pratique
• L’outillage moderne
• Les tutoriels du parcours
• Réalités du terrain
• Erreurs fréquentes
• FAQ
• Ressources officielles

Construire des interfaces qui tiennent dans le temps

Vous avez besoin d’une interface qui réagit instantanément à la moindre saisie, qui se découpe en morceaux réutilisables, et qui ne devient pas un plat de spaghettis au bout de six mois. C’est exactement le terrain de Vue. Ce framework JavaScript progressif permet de démarrer par une simple balise script dans une page existante, puis de monter en puissance jusqu’à une application complète rendue côté serveur, sans jamais changer d’outil.

Depuis la sortie de Vue 3, le framework s’est réorganisé autour d’une nouvelle façon d’écrire la logique des composants : la Composition API. Au moment d’écrire ces lignes, la version stable est Vue 3.5, et la branche 3.6 prépare en bêta un nouveau moteur de réactivité ainsi que le « Vapor Mode », une stratégie de compilation qui se passe du DOM virtuel pour les composants les plus sollicités. Autrement dit : l’écosystème est mûr, stable, et toujours en mouvement vers plus de performance.

Cette page sert de carte. Elle explique le quoi et le pourquoi de chaque pièce de l’écosystème — réactivité, composants, gestion d’état, routage, rendu serveur — et renvoie vers des tutoriels dédiés qui en montrent le comment, pas à pas. Tout au long du parcours, nous construisons un même projet réel : NoteFlux, un gestionnaire de notes personnelles avec recherche, favoris et fiches détaillées. Chaque tutoriel en assemble une brique.

Pourquoi Vue 3 aujourd’hui

Trois qualités expliquent la longévité de Vue : la progressivité, la lisibilité et la cohérence de l’écosystème officiel. Là où d’autres bibliothèques laissent le choix du routeur, du gestionnaire d’état et de la structure à l’écosystème tiers, Vue maintient des paquets officiels — Vue Router, Pinia, le compilateur de composants monofichiers — qui évoluent de concert. Vous n’avez pas à arbitrer entre douze bibliothèques concurrentes pour des besoins de base : la réponse officielle existe et elle est maintenue par la même équipe.

La réécriture interne de Vue 3 a apporté des gains concrets. La version 3.5 a réduit l’empreinte mémoire du système de réactivité d’environ 56 % et rendu les grands tableaux réactifs nettement plus rapides à parcourir. Ces chiffres ne sont pas cosmétiques : sur un appareil d’entrée de gamme, avec une connexion irrégulière, une application légère qui hydrate vite fait la différence entre un produit utilisable et un produit abandonné.

Le cœur conceptuel reste le composant monofichier (Single-File Component, extension .vue). Un seul fichier regroupe le gabarit HTML, la logique JavaScript et les styles encapsulés du composant. Cette colocation est l’une des raisons pour lesquelles un débutant lit un composant Vue et comprend en quelques minutes ce qu’il fait — tout est au même endroit, dans un ordre prévisible.

Ce que ce parcours vous permettra de faire

À la fin de l’ensemble des tutoriels, vous saurez :

• Créer un projet Vue 3 moderne avec Vite et l’écrire entièrement en Composition API et <script setup>.
• Modéliser un état réactif avec ref, reactive, computed et le surveiller avec watch, sans tomber dans les pièges de perte de réactivité.
• Découper une interface en composants, faire descendre des données par les props et remonter des actions par les events, jusqu’au v-model personnalisé.
• Centraliser l’état partagé d’une application avec Pinia, en séparant proprement données, getters et actions.
• Mettre en place une navigation multi-pages avec Vue Router, routes dynamiques et gardes de navigation.
• Servir l’application en rendu côté serveur avec Nuxt, puis la déployer sur un serveur Node ou en pages statiques.

Chaque objectif est démontrable : à la fin, vous aurez une application NoteFlux qui tourne, pas seulement une compréhension théorique.

Le parcours d’apprentissage

L’ordre compte. Les briques s’empilent, chacune supposant la précédente. Voici l’itinéraire conseillé :

1. La réactivité — le cœur de Vue. On comprend comment une donnée déclenche une mise à jour de l’écran. C’est le socle de tout le reste. Voir le tutoriel sur la réactivité.
2. Composants, props et events — comment découper l’interface et faire communiquer les morceaux. Voir le tutoriel sur les composants.
3. La gestion d’état avec Pinia — quand les données doivent être partagées entre plusieurs vues. Voir le tutoriel sur Pinia.
4. Le routage avec Vue Router — transformer l’application en plusieurs pages navigables. Voir le tutoriel sur Vue Router.
5. Rendu serveur et déploiement avec Nuxt — le rendu côté serveur pour le référencement et la performance, puis la mise en ligne. Voir le tutoriel sur Nuxt.

Si vous débutez complètement, suivez cet ordre. Si vous connaissez déjà les composants, vous pouvez sauter directement à Pinia ou à Vue Router selon votre besoin.

Les concepts fondamentaux

Le composant monofichier

Un fichier .vue contient trois blocs. Le bloc <template> décrit le HTML à afficher, augmenté de directives Vue (v-if, v-for, v-bind, v-on). Le bloc <script setup> contient la logique : déclarations d’état, fonctions, imports. Le bloc <style scoped> contient des styles qui ne fuient pas hors du composant. Voici la forme minimale :

<script setup>
import { ref } from 'vue'
const compteur = ref(0)
</script>

<template>
  <button @click="compteur++">Cliqué {{ compteur }} fois</button>
</template>

<style scoped>
button { padding: .5rem 1rem; }
</style>

Ce composant affiche un bouton dont le texte se met à jour à chaque clic. Aucune manipulation manuelle du DOM, aucun document.querySelector : on modifie une donnée (compteur) et Vue se charge de répercuter le changement à l’écran. C’est tout l’intérêt d’un framework réactif.

Les directives, le langage du gabarit

Dans le gabarit, Vue ajoute au HTML des attributs spéciaux appelés directives. v-if et v-show affichent ou masquent un élément selon une condition. v-for répète un élément pour chaque entrée d’un tableau. v-bind (raccourci :) lie un attribut HTML à une donnée — par exemple :class ou :href. v-on (raccourci @) attache un gestionnaire d’événement, comme @click. Enfin v-model crée une liaison bidirectionnelle entre un champ de formulaire et une donnée. Ces quelques directives couvrent l’écrasante majorité des besoins :

<input v-model="recherche" placeholder="Rechercher une note">
<ul>
  <li v-for="note in notesFiltrees" :key="note.id">
    {{ note.titre }}
  </li>
</ul>
<p v-if="notesFiltrees.length === 0">Aucune note ne correspond.</p>

Ce fragment, parfaitement lisible même pour qui découvre Vue, contient déjà une recherche en direct : on tape dans le champ, recherche se met à jour, notesFiltrees se recalcule, et la liste se redessine. L’attribut :key sur v-for n’est pas optionnel : il donne à Vue un identifiant stable pour suivre chaque élément lors des mises à jour, ce qui évite des bugs d’affichage subtils.

Le rendu déclaratif et le DOM virtuel

Vue est déclaratif : vous décrivez à quoi l’interface doit ressembler pour un état donné, et le framework calcule les modifications minimales à appliquer au document. Entre deux états, Vue compare une représentation légère de l’arbre (le DOM virtuel) et n’applique au vrai DOM que les différences. Vous raisonnez sur des données, jamais sur des opérations de bas niveau. Le futur Vapor Mode pousse cette logique encore plus loin en générant, pour certains composants, du code qui touche directement le DOM sans passer par cette représentation intermédiaire.

La réactivité, en une phrase

La réactivité, c’est le mécanisme qui relie une donnée à tout ce qui en dépend. Quand la donnée change, l’écran, les valeurs calculées et les effets de bord se mettent à jour automatiquement. C’est le concept le plus important de Vue et le sujet du premier tutoriel du parcours.

Options API et Composition API

Vue propose deux styles pour écrire un composant. L’Options API, historique, organise le code par type : un objet avec une clé data, une clé methods, une clé computed, etc. La Composition API, introduite avec Vue 3, organise le code par fonctionnalité : on regroupe au même endroit l’état, les valeurs calculées et les fonctions qui concernent une même préoccupation.

Comparez. En Options API :

export default {
  data() {
    return { recherche: '', notes: [] }
  },
  computed: {
    notesFiltrees() {
      return this.notes.filter(n => n.titre.includes(this.recherche))
    }
  }
}

La même logique en Composition API avec <script setup> :

import { ref, computed } from 'vue'

const recherche = ref('')
const notes = ref([])
const notesFiltrees = computed(() =>
  notes.value.filter(n => n.titre.includes(recherche.value))
)

La différence saute aux yeux quand un composant grossit. En Options API, la logique d’une même fonctionnalité se disperse entre data, computed et methods ; il faut faire des allers-retours. En Composition API, tout ce qui concerne « la recherche » tient en trois lignes consécutives. Surtout, cette logique devient extractible : on peut la sortir dans une fonction réutilisable — un composable — et la partager entre composants. C’est ce gain qui a fait de la Composition API le standard de fait de l’écosystème.

Ce gain n’est pas qu’esthétique. Imaginez que la logique de recherche serve dans trois écrans différents. En Composition API, vous la sortez dans une fonction useRecherche() qui renvoie l’état et les valeurs calculées, puis vous l’appelez dans chaque composant. C’est ce qu’on appelle un composable : une fonction réutilisable qui encapsule de la logique réactive. Les composables sont la véritable raison d’être de la Composition API ; ils remplacent les mixins de Vue 2 par un mécanisme explicite, sans conflits de noms ni magie cachée.

// composables/useRecherche.js
import { ref, computed } from 'vue'
export function useRecherche(source) {
  const terme = ref('')
  const resultats = computed(() =>
    source.value.filter(n => n.titre.toLowerCase().includes(terme.value.toLowerCase()))
  )
  return { terme, resultats }
}

N’importe quel composant peut désormais écrire const { terme, resultats } = useRecherche(notes) et obtenir une recherche fonctionnelle en une ligne. Cette capacité à composer la logique, et non à la dupliquer, est ce qui rend les grandes bases de code Vue 3 maintenables.

L’Options API n’est pas dépréciée et reste parfaitement valable. Mais tout le nouveau contenu officiel, la documentation des bibliothèques et l’outillage TypeScript visent désormais la Composition API. C’est elle que ce parcours emploie de bout en bout.

Pourquoi <script setup>

La syntaxe <script setup> est du sucre de compilation au-dessus de la Composition API. Elle supprime le passage par une fonction setup() et son return : toute variable ou fonction déclarée au premier niveau est automatiquement disponible dans le gabarit. Le code est plus court, mieux typé, et le compilateur peut optimiser davantage. C’est la forme recommandée pour tout nouveau composant.

Vue d’ensemble pratique

Voici les cinq briques que vous assemblerez, et le rôle de chacune dans NoteFlux.

La réactivité : faire vivre les données

Avant tout, il faut savoir déclarer un état qui réagit. ref enveloppe une valeur simple (un nombre, une chaîne, un objet) ; on lit et on écrit sa valeur via .value dans le script, et directement dans le gabarit. reactive rend un objet entier réactif. computed dérive une valeur à partir d’autres données réactives, avec mise en cache. watch exécute un effet quand une donnée surveillée change. Dans NoteFlux, c’est ce qui filtre les notes en direct pendant que l’utilisateur tape. Le tutoriel sur la réactivité détaille chacune de ces fonctions et leurs pièges.

Les composants : découper et réutiliser

Une interface réelle se compose de dizaines de morceaux. Une carte de note, une barre de recherche, un bouton favori : autant de composants. Les données descendent du parent vers l’enfant par les props ; les actions remontent de l’enfant vers le parent par les events. Cette circulation à sens unique — données vers le bas, événements vers le haut — rend le flux prévisible. Le tutoriel sur les composants construit la carte de note de NoteFlux et son v-model personnalisé.

Pinia : l’état partagé

Quand plusieurs vues ont besoin des mêmes données — la liste des notes affichée à la fois sur la page d’accueil et dans la barre latérale —, faire transiter ces données de composant en composant devient pénible. Pinia centralise cet état dans des stores. C’est la bibliothèque officielle de gestion d’état, légère et typée. Le tutoriel sur Pinia y déplace toute la logique des notes de NoteFlux.

Vue Router : plusieurs pages

Une application moderne a plusieurs écrans : la liste des notes, la fiche d’une note, une page de réglages. Vue Router associe une URL à un composant, gère l’historique du navigateur et protège certaines routes. Le tutoriel sur Vue Router transforme NoteFlux en application à plusieurs vues.

Nuxt : rendu serveur et mise en ligne

Une application Vue classique se rend dans le navigateur. Pour le référencement, le partage social et la performance perçue, on veut parfois que le serveur renvoie déjà du HTML rempli. C’est le rendu côté serveur (SSR), et Nuxt est le framework officiel qui l’apporte à Vue, en plus du routage par fichiers et du déploiement multi-plateformes. Le tutoriel sur Nuxt sert NoteFlux en SSR puis le met en ligne.

L’outillage moderne

Trois outils accompagnent tout projet Vue sérieux. Vite est le serveur de développement et le bundler par défaut : démarrage quasi instantané, rechargement à chaud, build optimisé. On crée un projet avec npm create vue@latest, qui propose une configuration interactive (TypeScript, Vue Router, Pinia, tests). Vue DevTools, l’extension de navigateur officielle, inspecte l’arbre des composants, l’état réactif et les stores Pinia en direct — indispensable pour déboguer. Enfin, TypeScript est de première classe dans Vue 3 : la Composition API a été conçue pour bien s’inférer, et l’outillage moderne (Volar) fournit l’autocomplétion jusque dans les gabarits.

Vous n’êtes pas obligé d’adopter TypeScript dès le premier jour. Mais sachez que tout l’écosystème y est taillé, et que les exemples de la documentation officielle l’emploient de plus en plus. Commencer en JavaScript pur reste un choix légitime pour apprendre les concepts sans la charge cognitive du typage.

Les tutoriels du parcours

Chaque tutoriel ci-dessous construit une brique de NoteFlux et peut se suivre seul, mais l’ensemble forme une progression cohérente.

Réalités du terrain

Quelques considérations pratiques qui pèsent quand on développe avec des moyens contraints. D’abord, le poids du bundle : une application Vue bien construite tient en quelques dizaines de kilo-octets compressés. Activez le découpage de code par route (le chargement paresseux des composants de page, vu dans le tutoriel Vue Router) pour ne charger que ce dont l’utilisateur a besoin. Sur une connexion mobile lente, c’est ce qui sépare une page qui s’affiche en une seconde d’une page qui ne charge jamais.

Ensuite, le coût d’hébergement. Une application Vue purement cliente se sert comme de simples fichiers statiques : n’importe quel hébergement de fichiers, y compris les offres gratuites de pages statiques, suffit. Ce n’est que lorsqu’on veut du rendu serveur (Nuxt en mode SSR) qu’il faut un processus Node qui tourne en continu, donc un petit serveur ou un service spécialisé. Le tutoriel Nuxt montre les deux options : le serveur Node persistant et la génération statique qui retombe sur un simple hébergement de fichiers.

Enfin, le développement hors ligne. Vite et l’écosystème npm mettent en cache les paquets installés ; une fois les dépendances téléchargées, vous travaillez sans connexion. Pensez à figer les versions dans package-lock.json pour des installations reproductibles, et à conserver le cache npm sur une machine de référence si la bande passante est partagée.

Erreurs fréquentes

FAQ

Faut-il connaître React ou Angular avant Vue ?
Non. Vue s’apprend très bien comme premier framework. Une bonne base en HTML, CSS et JavaScript moderne (fonctions fléchées, modules, déstructuration) suffit largement pour démarrer.

Composition API ou Options API pour débuter ?
La Composition API avec <script setup>. C’est le standard actuel, tout le contenu récent la vise, et elle prépare mieux à la lecture des bibliothèques officielles. L’Options API reste valable mais ne devrait plus être le point de départ d’un nouveau projet.

Vue 3 et Vue 2, c’est très différent ?
Le modèle mental est le même, mais Vue 2 a atteint sa fin de vie. Les nouveaux projets démarrent en Vue 3, et l’écosystème (Pinia, Vue Router 5) ne cible plus Vue 2. Apprenez directement Vue 3.

Ai-je besoin de Pinia dès le début ?
Non. Tant que l’état reste local à un composant ou se partage entre un parent et quelques enfants par props et events, vous n’avez pas besoin d’un store. Pinia devient utile quand les mêmes données doivent vivre dans plusieurs branches éloignées de l’arbre.

Quelle différence entre Vue et Nuxt ?
Vue est la bibliothèque de composants et de réactivité. Nuxt est un framework bâti au-dessus de Vue qui ajoute le rendu côté serveur, le routage par fichiers, l’optimisation et le déploiement. On apprend Vue d’abord, Nuxt quand on a besoin de SSR ou d’une structure clé en main.

TypeScript est-il obligatoire ?
Non, mais fortement recommandé pour les projets qui durent. La Composition API est pensée pour bien s’inférer, et l’autocomplétion qui en découle réduit beaucoup les erreurs. On peut tout à fait commencer en JavaScript et migrer progressivement.

Peut-on ajouter Vue à un site qui existe déjà ?
Oui, c’est même l’un de ses points forts. On peut charger Vue depuis un CDN par une simple balise script et ne l’activer que sur une portion de page — un formulaire dynamique, un widget interactif — sans réécrire tout le site ni mettre en place de chaîne de build. C’est la « progressivité » de Vue : on adopte autant de framework qu’on en a besoin, et on monte en puissance vers une application complète seulement si le projet le justifie.

En combien de temps devient-on productif ?
Avec une base solide en JavaScript, on écrit des composants utiles en quelques jours. La réactivité et les composants s’assimilent vite ; Pinia, le routage et le SSR viennent ensuite, au fil des besoins réels du projet. Suivre les tutoriels dans l’ordre, en construisant NoteFlux, donne un repère concret pour mesurer sa progression.

Ressources officielles

• Documentation officielle de Vue — le guide et la référence de l’API.
• Annonce de Vue 3.5 — les nouveautés détaillées par l’équipe Vue.
• Documentation de Pinia — la gestion d’état officielle.
• Documentation de Vue Router — le routeur officiel.
• Documentation de Nuxt — le framework SSR pour Vue.