Migration Vue 2 vers Vue 3 : Approche boostée par Claude Code

Introduction

Vue 2 est officiellement en fin de vie depuis le 31 décembre 2023. Pourtant, il est possible que certaines de vos applications Vue en production tournent encore sur cette version — et chaque mois qui passe creuse un peu plus la dette technique.

La bonne nouvelle : la migration vers Vue 3 est aujourd’hui mieux documentée qu’elle ne l’a jamais été et les outils sont là.

Avec Claude Code comme co-pilote technique — pour auditer le code, identifier les breaking changes, générer des plans de migration et assister la correction composant par composant — ce qui ressemblait à un chantier redouté devient un projet planifiable et livrable par phases.

Pourquoi migrer maintenant — et pas dans six mois

Vue 2 est un cul-de-sac technique

La fin de vie officielle ne signifie pas que votre application cesse de fonctionner demain matin. Elle signifie quelque chose de plus insidieux : l’écosystème vous tourne progressivement le dos.

Les librairies majeures de l’univers Vue ont déjà basculé :

• Vue Router 4 pour la gestion de navigation — Vue 3 uniquement.
• Vuex 5 / Pinia — Le nouveau standard pour la gestion des stores - Vue 3 uniquement.
• VueUse — la librairie de composables la plus populaire de l’écosystème — Vue 3 uniquement.
• Nuxt 3 — Vue 3 uniquement.
• La plupart des UI kits actifs (Vuetify 3, PrimeVue 4, Quasar 2+) ont abandonné leur branche Vue 2.

Rester sur Vue 2, c’est se condamner à utiliser des versions figées de ces outils, à patcher manuellement les failles de sécurité que personne ne corrige plus, et à recruter des développeurs sur une stack que la communauté considère comme obsolète.

Vue 3 n’est pas juste une mise à jour cosmétique

Vue 3 apporte des changements structurants :

• La Composition API : une façon d’organiser la logique des composants par fonctionnalité plutôt que par option (data, methods, computed…). Le code est plus réutilisable, plus testable, plus lisible sur les gros composants.
• Un système de réactivité basé sur Proxy : plus prévisible, plus complet, sans les angles morts de Object.defineProperty (ajout de propriétés dynamiques, tableaux, etc.).
• Un meilleur support TypeScript natif : les types sont intégrés dans le cœur du framework, garantissant une détection des erreurs au plus tôt (compilation vs exécution).
• Des performances améliorées : temps de montage réduit, moins de travail dans le virtual DOM grâce au compilateur de templates optimisé.

---

Guide technique de migration Vue 2 vers Vue 3 : quatre phases, zéro régression

Sur les migrations que nous accompagnons, nous avons structuré le travail en quatre sous-phases distinctes (+ une cinquième optionnelle bonus). Chacune a un critère de sortie clair et peut faire l’objet d’une mise en production indépendante.

flowchart TD
    P1["Phase 1\nMettre à jour Node LTS et supprimer les Polyfills"] --> P2["Phase 2\nNettoyage pré-migration"]
    P2 --> P3["Phase 3\nUpdate des dépendances Vue 3 et ajout de vue/compat"]
    P3 --> P4["Phase 4\nMigration progressive via vue/compat jusqu'à support complet"]
    P4 --> P5["Phase 5 (optionnel)\nMise à jour des outils de développement"]

Phase 1 - Mettre à jour Node LTS et supprimer les Polyfills

Cette étape est souvent sous-estimée. On imagine que mettre à jour Node est un détail d’infrastructure, séparable du reste. Ce n’est pas le cas.

La version de l’environnement d’exécution conditionne directement la résolution des dépendances, le comportement des outils de build, et la compatibilité des plugins. Sauter cette étape ou la traiter après coup, c’est s’exposer à des erreurs de build difficiles à diagnostiquer, sans lien apparent avec Vue.

Cette montée de version est aussi l’occasion de faire un premier passage de nettoyage sur les polyfills. La LTS de Node embarque nativement des APIs qui nécessitaient autrefois des shims côté bundle — et que votre package.json traîne peut-être encore.

Quelques exemples concrets de polyfills devenus inutiles sur Node 24 et les navigateurs actuels :

• promise-polyfill : les Promise sont natives depuis Node 0.12 et dans 100 % des navigateurs modernes.
• polyfill-array-includes : Array.prototype.includes() est ES2016, supporté nativement partout.
• document-register-element : polyfill pour Custom Elements v0, une API obsolète même selon le W3C — remplacée par Custom Elements v1, native dans tous les navigateurs modernes.

Chaque polyfill supprimé, c’est du code mort en moins dans le bundle final — et une dépendance de moins à maintenir pour la suite de la migration.

Avec Claude Code, cette étape prend quelques minutes : citez votre @package.json en contexte et demandez-lui de lister les polyfills devenus inutiles sur Node 24+. Il croise vos dépendances avec la compatibilité native des environnements cibles et vous propose directement les suppressions à effectuer — avec justification pour chacune.

Vous trouverez plus bas dans l’article un template de prompt pour guider l’IA dans ce sens.

Phase 2 — Nettoyage pré-migration

Avant de toucher à Vue, on supprime tout ce qui est mort ou inutilisé. L’objectif est simple : réduire la surface à migrer.

C’est la phase où Claude Code est le plus efficace en autonomie. Citez vos fichiers d’entrée (main.js, router, stores) et demandez-lui d’effectuer l’audit de nettoyage. Il va :

• Détecter les composants Vue jamais importés (avec leurs dépendances fantômes qui n’entrent jamais dans le graphe Webpack)
• Identifier les plugins enregistrés mais jamais consommés — exemple : un vue-match-media branché dans main.js qu’aucun composant n’utilise
• Lister les filtres globaux déclarés mais jamais appelés dans un template
• Signaler les appels à des APIs enlevés en Vue 3 (Vue.config.productionTip, etc.) qu’on peut supprimer dès maintenant

Le résultat est une liste de suppressions actionnables, fichier par fichier. Claude peut aussi générer les diffs directement si vous l’y autorisez.

Cette phase ne change rien au comportement de l’application. Elle ne produit que des suppressions. Et c’est précisément ce qui la rend MEP-able immédiatement, sans risque.

Phase 3 — Bascule Vue 3 + @vue/compat en MODE compatible vue2

C’est la phase de bascule technique. On monte les dépendances majeures (Vue ^3, Vue Router ^4, Vuex ^4), on adapte les scripts d’instanciation des app Vue, et on ajoute la librairie utilitaire @vue/compat qui permet d’émuler le comportement de Vue 2 pour une migration progressive.

Dans la suite de l’article nous détaillions le fonctionnement de @vue/compat en profondeur.

À la fin de cette phase, le projet tourne sur Vue 3 — mais avec un comportement identique à Vue 2.

Ici aussi il est possible de MEP pour ne pas geler le projet si d’autres features doivent être déployées en parallèle. Cette phase est aussi transparente pour les utilisateurs finaux.

Claude Code est particulièrement utile ici pour adapter les scripts d’instanciation : il connaît la syntaxe createRouter(), createStore(), createApp() de Vue 3 et peut réécrire vos fichiers d’entrée en quelques secondes une fois le contexte de votre main.js fourni.

Phase 4 — Sortie progressive du compat mode

On traite les breaking changes composant par composant. Pour chaque composant migré, on désactive le compat mode localement et on vérifie qu’aucun warning ne remonte en console. Une fois tous les composants traités, on retire @vue/compat du package.json.

Claude dans la boucle compat : pour chaque warning [Vue compat] en console, copiez le message et le composant concerné dans votre session Claude Code. Il identifie le pattern déprécié, propose la syntaxe Vue 3 équivalente et génère le diff à appliquer. Sur les breaking changes les plus courants (v-model, $set/$delete, slots, composants async), le traitement par composant prend moins d’une minute.

Phase 5 (optionnelle) - Mise à jour des outils de développement

Cette phase n’a aucun impact sur la logique métier ni sur l’expérience utilisateur. Elle concerne exclusivement l’environnement de développement — c’est pourquoi elle est optionnelle et planifiable selon les préférences et la disponibilité de l’équipe.

Vitejs à la place de Vue CLI / Webpack

@vue/cli-service est officiellement en mode maintenance. Vue 3 fonctionne parfaitement avec Vue CLI 5, donc rien n’oblige à migrer — mais Vite offre un démarrage à froid quasi-instantané et un HMR nettement plus réactif sur les projets modernes. Le point de vigilance principal est la réécriture de vue.config.js et la migration des variables d’environnement (VUE_APP_* → VITE_*). À ne pas mélanger avec la migration Vue 3 elle-même : deux chantiers séparés.

Vitest à la place de Jest

Conçu nativement pour Vite, Vitest partage une syntaxe quasi-identique à Jest — la migration des specs existantes est généralement minime. Si vous passez à Vite, c’est le bon moment pour en profiter. Si vous restez sur Webpack, Jest reste une option parfaitement valide.

Gestionnaire de paquets

Si le projet tourne encore sous npm, la migration vers pnpm ou yarn (lockfile déterministe, performances d’installation, gestion des workspaces) peut valoir le coup. C’est avant tout une préférence d’équipe — à arbitrer collectivement plutôt qu’à décider seul en cours de migration Vue.

---

@vue/compat : votre filet de sécurité pour une migration sans rupture

Dans cette section de notre guide de migration nous détaillons l’usage de @vue/compat, un build spécial de Vue 3 qui émule le comportement de Vue 2 tout en levant des avertissements dans la console sur chaque usage déprécié. C’est l’outil officiel recommandé par l’équipe Vue pour les migrations progressives.

Activation

Dans package.json, on remplace vue: ^2.x par vue: ^3.4 et on ajoute @vue/compat: ^3.4 en ciblant la même version, et on ajoute l’alias Webpack nécessaire :

// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.resolve.alias.set('vue', '@vue/compat')
  }
}

Dans votre fichier d’instanciation de Vue (main.js), on configure vue/compat au global :

import { configureCompat } from 'vue'

// MODE 2 = comportement Vue 2 par défaut,
// warnings sur chaque usage déprécié détecté.
configureCompat({ MODE: 2 })

À partir de là, votre application démarre, votre build passe, vos tests passent — et votre console liste précisément tout ce qu’il reste à corriger, fichier par fichier, ligne par ligne.

Ce que ça donne en pratique : l’exemple des composants asynchrones

En Vue 2, il est possible de déclarer des composants chargés de façon asynchrone avec une simple arrow function :

// Vue 2 — syntaxe dépréciée en Vue 3
export default {
  components: {
    formulaire: () => import('./views/Formulaire'),
    landing: () => import('./views/Landing')
  }
}

En Vue 3, cette syntaxe est remplacée par defineAsyncComponent :

// Vue 3 — syntaxe correcte
import { defineAsyncComponent } from 'vue'

export default {
  components: {
    formulaire: defineAsyncComponent(() => import('./views/Formulaire')),
    landing: defineAsyncComponent(() => import('./views/Landing'))
  }
}

Avec @vue/compat activé en MODE 2, Vue 3 accepte les deux syntaxes — mais affiche un warning [Vue compat]: COMPONENT_ASYNC pour chaque usage de l’ancienne forme.

Dans cet exemple on peut aussi voir @vue/compat à l’oeuvre directement depuis l’extension Vue.js devtools qui intercale le composant AsyncComponentWrapper là où l’import à lieu.

Stratégie de sortie : composant par composant

Une fois un composant corrigé, on peut désactiver le compat mode localement en ajoutant une option compatConfig dans son bloc <script> :

export default {
  compatConfig: { MODE: 3 },
  // ... reste du composant en Vue 3 pur
}

Cela permet de valider progressivement chaque composant sans attendre que tous soient migrés.

Quand plus aucun composant en MODE 3 ne lève de warning en console, on retire @vue/compat du package.json et la config configureCompat globale. La migration est terminée.

flowchart TD
    A([Prendre un composant]) --> B{Warnings compat\nen console ?}
    B -- Oui --> C[Corriger les usages\ndépréciés]
    C --> B
    B -- Non --> D["Ajouter compatConfig: MODE 3\ndans le composant"]
    D --> E{Composants\nrestants ?}
    E -- Oui --> A
    E -- Non --> F["Retirer vue/compat\net configureCompat"]
    F --> G([Migration terminée])

---

Audit de code et plan de migration Vue 3 avec Claude Code

La phase d’audit est souvent la plus chronophage. Sur une codebase de taille moyenne (50 à 150 composants), cartographier manuellement tous les breaking changes, identifier les dépendances à migrer, et estimer l’effort par sous-phase peut prendre plusieurs jours — Claude Code compresse ce travail à quelques heures.

Pour lui donner accès à la documentation Vue 3 à jour pendant la session, nous utilisons le MCP context7 — notamment avec la source v3-migration.vuejs.org qui couvre l’intégralité du guide de migration officiel.

Pour l’ajouter à Claude Code :

# cf. doc d'install https://context7.com/docs/clients/claude-code
npx ctx7 setup --claude

Grâce à ce contexte documentaire en temps réel, Claude peut croiser les informations de votre codebase avec les breaking changes documentés et structurer sa réponse en phases actionnables.

Le workflow

1. Citez les fichiers clés de votre projet : @package.json, vos fichiers d’entrée (main.js, point d’entrée du router, des stores), et optionnellement vos composants les plus complexes.
2. Soumettez-les à Claude Code avec le prompt ci-dessous.
3. Obtenez un plan structuré par phases, avec les breaking changes identifiés fichier par fichier.
4. Dépiler chaque phase de manière unitaire pour vous laisser la possibilité de mettre en production à n’importe quel moment.

Template de prompt pour l’audit de code Vue 2 et génération de plan de migration Vue 3 avec Claude Code

Tu es un expert Vue.js avec une connaissance approfondie de la migration Vue 2 vers Vue 3 et utilise la documentation context7 "Vue 3 Migration Guide".

Analyse ce projet Vue 2 et produis un plan de migration structuré en quatre phases :
1. Montée de version de Node sur la dernière LTS, détecte les éventuels polyfills à supprimer
2. Nettoyage pré-migration (composants morts, libs inutilisées, APIs supprimées en Vue 3)
3. Bascule Vue 3 + @vue/compat en MODE 2 (mise à jour des dépendances, refonte des points d'entrée, libs tierces)
4. Sortie progressive du compat mode (breaking changes par composant)

Pour chaque phase :
- Liste les fichiers à modifier et les changements précis à effectuer
- Identifie les pièges spécifiques à ce projet
- Donne le critère de sortie de phase (comment savoir qu'on peut MEP)

Lit le @package.json et les fichiers d'entrée du projet :

[collez ici le contenu de vos fichiers]

Exemple simplifié du résultat attendu

Le contenu réel du résultat sera bien évidamment plus long et plus précis en rapport direct avec la codebase de votre projet. L’exemple suivant sert juste d’illustration de ce à quoi s’attendre comme format du plan de migration.

Phase 1 — Impact montée de version de Node
──────────────────────────────────────────
• Supprimer les polyfills suivant de votre package.json : promise-polyfill, polyfill-array-includes ...

Critère de sortie : yarn build, yarn test:unit et yarn build-storybook verts.
git diff --stat ne montre que des suppressions. MEP possible.

Phase 2 — Nettoyage pré-migration
──────────────────────────────────
• vue-match-media : grep "$mq" → 0 résultat → supprimer import, Vue.use(), et le bloc mq: {} dans App.vue
• Composants orphelins détectés : Popup.vue (importe gsap absent de package.json),
• Vue.config.productionTip = false : noop en Vue 3, générera un warning compat → supprimer
...

Critère de sortie : yarn build, yarn test:unit et yarn build-storybook verts.
git diff --stat ne montre que des suppressions. MEP possible.

Phase 3 — Bascule Vue 3 + @vue/compat MODE 2
─────────────────────────────────────────────
• vue → @vue/compat + alias webpack, vue-template-compiler → supprimer
• vue-router → v4 : createRouter(), createWebHistory(), catch-all * → /:pathMatch(.*)*
• vuex → v4 : createStore(), supprimer Vue.use(Vuex)
• configureCompat({ MODE: 2 }) dans main.js et siteApp.js
...

Critère de sortie : build vert sur tous les environnements, smoke test manuel, MEP possible.

Phase 4 — Sortie compat mode
─────────────────────────────
• v-model : 7 composants déclarent prop value + émettent input
  → migrer vers modelValue / update:modelValue
• $set / $delete : 4 fichiers → remplacer par assignation directe (Proxy natif)
• Composants async : defineAsyncComponent() dans App.vue et RenderPage.vue
• ref dynamique dans v-for : RenderNestedPage.vue → function ref
...

Critère de sortie : aucun warning [Vue compat] en console sur l'ensemble des parcours.
Retrait de @vue/compat et de configureCompat des fichiers d'entrée.

C’est précisément là que se situe notre valeur ajoutée : Claude Code compresse la phase d’audit de plusieurs jours à quelques heures, et nous appliquons notre expertise pour affiner, prioriser, et exécuter le plan sans régression.

Conclusion

La migration Vue 2 → Vue 3 n’est plus une question de “si”, mais de “quand et comment”.

En combinant la documentation officielle de Vue en temps réel (via le MCP context7) et l’analyse directe de votre codebase, Claude Code permet de drastiquement réduire le temps global de cette migration.

Avec notre approche en phases, @vue/compat comme filet de sécurité pour ne jamais casser la production, et Claude Code comme accélérateur à chaque étape — détection de code mort, audit des dépendances, migration progressive des composants — ce chantier devient découpable par étapes clair sans vous laisser dans le flou.

Aujourd’hui nous avons pris le partie d’utiliser IA pour booster notre savoir-faire et notre éxécution amenant un réel avant-après en terme d’éxécution et satisfaction client dans la réalisation de nos migration Vue3.

---

Liens utiles

• Guide officiel de migration Vue 2 → Vue 3
• Migration Build (@vue/compat) — documentation officielle
• Liste complète des breaking changes Vue 3