Vue.js 3 APIs - Guide Complet et Comparatif

Vue.js 3 introduit deux approches principales pour structurer les composants :

• L’API Options (mode historique, héritée de Vue 2)
• L’API Composition (vue 3+, recommandée pour la majorité des nouveaux projets complexes)

L’API Options propose une organisation par sections (data, computed, methods…), idéale pour prendre en main le framework. L’API Composition, quant à elle, bouleverse cette organisation pour privilégier la modularité, la réutilisabilité et une meilleure intégration TypeScript.

1. L’API Options

Description

• Structure naturelle, facile à lire : chaque “type” de donnée ou logique (état, méthodes, calculs, watchers, etc.) est séparé en blocs dédiés.
• Chaque composant est un objet avec des options (data, computed, methods, etc.).
• Idéale pour : des commencements rapides, les projets simples, l’onboarding de nouveaux venus.

Exemple type

export default {
  data() { return { count: 0 } },
  computed: {
    double() { return this.count * 2 }
  },
  methods: {
    incr() { this.count++ }
  },
  mounted() { console.log('mounted!') }
}

Avantages

• Courbe d’apprentissage douce
• Lecture rapide, structure évidente
• Excellente documentation et communauté

Limites

• Logique métier éclatée (un même “comportement” requiert de modifier plusieurs blocs différents)
• Réutilisation difficile : les mixins deviennent rapidement source de bugs et conflits
• Typage TypeScript limité (difficulté d’inférence de types)
• Scalabilité moyenne pour les gros projets

2. L’API Composition

Description

• Tout se passe dans la fonction setup() (ou <script setup>)
• On importe des helpers (ref, reactive, computed…), on crée des fonctions dites “composables”
• Idéale pour : projets ambitieux, factorisation avancée, logique métier complexe, typage strict (TypeScript)

Exemple type

<script setup>
import { ref, computed } from 'vue'
const count = ref(0)
const double = computed(() => count.value * 2)
function incr() { count.value++ }
</script>

Avantages

• Logique regroupée par fonctionnalité
• Réutilisation avancée grâce aux composables
• Support TypeScript natif et performant
• Performances accrues (variables directement exposées, meilleur tree-shaking, moins d’overhead)

Inconvénients

• Courbe d’apprentissage plus raide si on débute
• Plus de code “bas niveau” pour des tâches simples
• Exige de gérer le regroupement et les conventions en équipe

3. Comparatif & Cas d’usage

4. Migration & Coexistence

Vue.js 3 permet de combiner les deux APIs dans le même projet :

• Parfait pour une migration progressive
• Possible d’initialiser une nouvelle logique métier en Composition, tout en gardant l’Option pour l’existant

5. Points techniques avancés

• Réactivité : repose désormais sur les Proxies natifs, contrôle fin via readonly, shallowRef, etc.
• TypeScript : l’API Composition simplifie la déclaration de types et la documentation runtime
• Hooks de cycle de vie : l’équivalent de mounted, beforeUnmount, etc. existe en version “onMounted”, “onUnmounted”, etc.
• Provide/Inject : intégration directe, plus naturelle dans l’API Composition

6. Performances

• Moins d’overhead : le template accède directement aux refs et computed, sans avoir besoin d’un proxy d’instance
• Composables factorisables et “tree-shakéables”
• Meilleur contrôle de la granularité de la réactivité (précis dans ce qui est rendu réactif, et comment)

7. En résumé : Quand choisir quoi ?

• API Options
  • Projets simples à moyens
  • Formation, documentation, communauté historique
  • Code facile à onboarding/maintenir si peu de logique à factoriser
• API Composition
  • Projets complexes/ambitieux
  • Besoin de factorisation/RX avancée/TypeScript
  • Logiciel sujet à croissance forte, équipe nombreuse ou expérience partagée

Recommandation

L’API Composition va s’imposer comme la référence sur les nouveaux projets Vue. Elle ne remplace pas l’API Options (qui reste maintenue), mais pour tout projet ambitieux, ou toute équipe souhaitant grandir, la Composition offre une lisibilité, une évolutivité et une puissance sans commune mesure.

Pour aller plus loin :

• Documentation Vue.js officielle,
• API Reference
• Considering performance, and why we switched to composition - Christophe Marchadour