Migration von Vue 2 auf Vue 3 realistisch planen

1. Ausgangslage: was Vue 2 EOL wirklich bedeutet

Vue 2 hat im Dezember 2023 sein End-of-Life erreicht. Das bedeutet konkret: Keine Sicherheitsupdates mehr, keine Bug-Fixes, keine neuen Features. Für Anwendungen in der Produktion ist das nicht sofort ein Problem — Vue 2 läuft weiter, und der Browser merkt nichts davon. Das Problem entsteht schleichend: Abhängigkeiten, die sich weiterentwickeln, werden die Kompatibilität mit Vue 2 einstellen. Build-Tools werden es nicht mehr unterstützen. Neue Mitarbeiter kennen Vue 2 nicht mehr aus ihrer Ausbildung. Irgendwann ist die Vue 2 Migration auf Vue 3 nicht mehr optional, sondern erzwungen — und dann unter schlechteren Bedingungen.

Wer die Vue 3 Migration jetzt freiwillig plant, hat Kontrolle über den Zeitpunkt und die Strategie. Wer wartet, bis eine kritische Bibliothek die Vue-2-Unterstützung einstellt, macht die Migration unter Druck, mit wenig Spielraum für schrittweise Anpassungen. Die gute Nachricht: Vue 3 ist in den meisten Bereichen eine substantielle Verbesserung — schnelleres reaktives System, bessere TypeScript-Unterstützung, kleinere Bundle-Größen. Die Investition lohnt sich. Die schlechte Nachricht: Es ist wirklich eine Migration, kein Update.

2. Inventur vor der Migration: was alles betroffen ist

Vor dem ersten npm install vue@3 steht eine Inventur. Diese Inventur ist der wichtigste Schritt der gesamten Vue 2 auf Vue 3 Migration und wird am häufigsten übersprungen. Was gehört in die Inventur: Alle Vue-Plugins und ihre Vue-3-Kompatibilität. Alle UI-Bibliotheken (Vuetify 2 → Vuetify 3 ist eine eigene große Migration). Alle Vuex-Stores und ihre Größe. Alle Vue Router-Konfigurationen. Alle Tests und ob sie Vue-Internals mocken. Alle Build-Tool-Konfigurationen (Webpack → Vite, oder Webpack weiter nutzen).

Das Ergebnis der Inventur ist eine Migrations-Matrix: welche Teile des Projekts wie stark betroffen sind und in welcher Reihenfolge sie angegangen werden müssen. Typischerweise stellt sich heraus, dass nicht die Vue-Kern-API das größte Problem ist, sondern eine einzige UI-Bibliothek oder ein internes Plugin, das intensiv Vue-Internals nutzt. Diese Blocker früh zu identifizieren und ihre Migration-Aufwände realistisch einzuschätzen, verhindert den häufigsten Fehler beim Vue Migration-Projekt: nach drei Wochen an einer Wand zu stehen, die am Anfang nicht sichtbar war.

// Migration audit script — run before starting Vue 3 migration
// Scans package.json for known Vue-2-only packages
import { readFileSync } from 'fs'

const pkg = JSON.parse(readFileSync('./package.json', 'utf8'))
const deps = { ...pkg.dependencies, ...pkg.devDependencies }

// Packages that require attention during Vue 2 → Vue 3 migration
const migrationMap = {
  'vuex':                    'Replace with Pinia (recommended) or upgrade to Vuex 4',
  'vue-router':              'Upgrade to vue-router 4 — breaking API changes',
  'vuetify':                 'Vuetify 2 → Vuetify 3 is a significant separate migration',
  'element-ui':              'Replace with Element Plus (Vue 3 fork)',
  'vue-i18n':                'Upgrade to vue-i18n 9 — composition API changes',
  '@vue/test-utils':         'Upgrade to @vue/test-utils v2',
  'vue-class-component':     'No Vue 3 equivalent — rewrite to Composition API required',
  'vue-property-decorator':  'No Vue 3 equivalent — rewrite required',
  'vuex-module-decorators':  'No Vue 3 equivalent — rewrite required',
}

Object.entries(migrationMap).forEach(([pkg, note]) => {
  if (deps[pkg]) {
    console.warn(`[MIGRATION REQUIRED] ${pkg}: ${note}`)
  }
})

3. Die echten Breaking Changes — nicht nur die offensichtlichen

Die offizielle Vue-3-Migrationsdokumentation listet die Breaking Changes auf — aber einige sind in der Praxis deutlich schmerzhafter als andere. Der wichtigste: Das globale Vue-Objekt gibt es nicht mehr. Stattdessen erzeugt createApp() isolierte Anwendungsinstanzen. Das klingt harmlos, bricht aber alle Plugins, die Vue.prototype erweitern oder Vue.use() global aufrufen. Viele interne und kommerzielle Plugins nutzen genau diese Muster — und müssen entweder ersetzt oder angepasst werden.

Ein weiterer echter Schmerz: $listeners ist in Vue 3 in $attrs aufgegangen. Code, der v-on="$listeners" verwendet, bricht still — keine Fehlermeldung, die Event-Handler funktionieren einfach nicht mehr. Das betrifft besonders Wrapper-Komponenten, die Events durchreichen. Gleiches gilt für .sync-Modifier, der durch v-model:propName ersetzt wurde, und für $scopedSlots, das in $slots aufgegangen ist. Diese Änderungen produzieren keine Compile-Time-Fehler und keine Runtime-Exceptions — sie produzieren Bugs, die erst im Testing auffallen.

4. Der Vue Migration Build als Brückenstrategie

Der offizielle Vue Migration Build (@vue/compat) ist eine spezielle Vue-3-Version, die Vue-2-Features mit Deprecation-Warnungen emuliert. Er ermöglicht, eine Vue-2-Anwendung schrittweise auf Vue 3 zu migrieren — zuerst auf den Migration Build umstellen, dann Feature für Feature migrieren, bis keine Warnings mehr im Build erscheinen, und dann auf normales Vue 3 wechseln. Das ist die empfohlene Strategie für große Codebasen, die nicht als Big-Bang-Rewrite migriert werden können.

Die Einschränkungen des Migration Builds sind jedoch erheblich und werden oft unterschätzt. Er ist deutlich langsamer als normales Vue 3 — nicht für den Produktionseinsatz geeignet. Er unterstützt nicht alle Vue-2-Features vollständig. Viele Bibliotheken funktionieren nicht korrekt damit, weil sie ebenfalls auf Vue-3-Internals zugreifen. Der Migration Build ist ein Analyse-Werkzeug und eine Brücke, kein dauerhafter Zustand. Teams, die ihn einsetzen, sollten ihn als befristete Phase behandeln, nicht als permanente Lösung für die Koexistenz von Vue 2 und Vue 3.

// vite.config.ts — enable Vue Migration Build for gradual Vue 3 migration
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          compatConfig: {
            MODE: 2,  // emulate Vue 2 behaviour with deprecation warnings
          },
        },
      },
    }),
  ],
  resolve: {
    alias: {
      // Redirect vue imports to the compat build
      vue: '@vue/compat',
    },
  },
})

// main.ts — configure compat globally
import { createApp, configureCompat } from '@vue/compat'
import App from './App.vue'

// Enable all Vue 2 compat features — disable them one by one as you migrate
configureCompat({ MODE: 2 })

createApp(App).mount('#app')

5. Von Options API zu Composition API: wann und wie umsteigen

Die Vue 3 Migration erfordert nicht, alle Komponenten sofort auf die Composition API umzuschreiben. Vue 3 unterstützt die Options API weiterhin vollständig — und wird das auch in absehbarer Zukunft tun. Die Entscheidung, wann eine Komponente auf die Composition API umgestellt wird, sollte pragmatisch sein: Komponenten, die ohnehin angepasst werden müssen, können dabei umgestellt werden. Komponenten, die stabil laufen und nie angefasst werden, dürfen in der Options API bleiben.

Die Composition API bringt vor allem dann echten Mehrwert, wenn Logik zwischen mehreren Komponenten geteilt wird. Was in Vue 2 Mixins erforderte — mit all ihren Namenskonflikten, impliziten Abhängigkeiten und schlechter TypeScript-Unterstützung — lässt sich in Vue 3 als sauberes Composable mit expliziten Inputs und Outputs formulieren. Die Migration von Mixins zu Composables ist einer der wenigen Bereiche, in dem die Vue 3 Migration den Code nicht nur kompatibel macht, sondern messbar verbessert.

6. Bibliotheken und ihre Migration: Vuex, Vue Router, UI-Libraries

Die Migration des State-Managements ist bei den meisten Projekten ein eigenes Mini-Projekt. Vuex 4 ist die Minimal-Option: Es funktioniert mit Vue 3, behält aber die Options-API-Syntax und alle bekannten Vuex-4-Einschränkungen. Pinia ist die empfohlene Langzeitstrategie: leichter, besser typisiert, kein Boilerplate für Actions und Mutations. Die Migration von Vuex zu Pinia lässt sich schrittweise durchführen — Store für Store —, und beide können temporär parallel existieren.

Bei UI-Bibliotheken ist die Situation oft die schmerzhafteste Stelle der gesamten Vue 2 auf Vue 3 Migration. Vuetify 2 auf Vuetify 3 ist eine eigene, umfangreiche Migration mit geänderten Komponentennamen, neuer Theme-API und Breaking Changes in der Grid-Syntax. Element UI wurde als Element Plus für Vue 3 neu entwickelt, ist aber keine Drop-in-Ersetzung. Quasar und PrimeVue haben Vue-3-Versionen mit unterschiedlichen API-Änderungen. Das Einplanen der UI-Bibliotheks-Migration als eigene Phase — mit eigenem Testing-Zeitraum — ist der häufig fehlende Puffer im Migrationsplan.

7. Teststrategie für die Migration

Tests sind bei der Vue 3 Migration gleichzeitig das wichtigste Sicherheitsnetz und eine potenzielle Bremse. Das wichtigste Sicherheitsnetz: Integrations- und E2E-Tests, die gegen die laufende Anwendung testen, ohne Vue-Internals zu mocken. Sie überleben die Migration weitgehend unverändert, weil sie die UI aus Nutzerperspektive testen. Die potenzielle Bremse: Unit-Tests, die Vue-Internals direkt verwenden — Wrapper-Mounting mit vielen manuellen Mocks auf Vue-APIs, Test auf spezifische Emit-Strukturen oder direkte Zugriffe auf Komponenteninstanzen.

Die Migration von @vue/test-utils von Version 1 auf Version 2 bringt eigene Breaking Changes mit sich: Die shallowMount-Semantik hat sich geändert, find und findAll verhalten sich anders, und viele Optionen wurden umbenannt. Realistische Einschätzung: Für eine mittelgroße Vue-2-Anwendung mit guter Testabdeckung beträgt der reine Testing-Migrationsaufwand 20–30 % des gesamten Migrationsaufwands. Diesen Anteil im Zeitplan zu unterschlagen ist einer der häufigsten Gründe, warum Vue Migration-Projekte länger dauern als geplant.

8. Realistischer Zeitplan für verschiedene Codebase-Größen

Ein ehrlicher Zeitplan für die Vue 2 auf Vue 3 Migration hängt primär von zwei Faktoren ab: der Anzahl der Komponenten und der Komplexität der verwendeten Bibliotheken. Kleine Anwendungen mit unter 50 Komponenten, wenig externen Bibliotheken und guter Testabdeckung: 2–4 Wochen mit einem erfahrenen Entwickler. Mittlere Anwendungen mit 50–200 Komponenten, Vuex, Vue Router und einer UI-Bibliothek: 2–3 Monate für ein kleines Team. Große Anwendungen mit 200+ Komponenten, mehreren Vuex-Modulen, komplexer UI-Bibliothek und Legacy-Plugins: 4–8 Monate in phasenweiser Durchführung.

Diese Schätzungen setzen voraus, dass die Migration neben dem normalen Produktionsbetrieb läuft — neue Features werden weiterhin in Vue 2 entwickelt, während die Migration in einem parallelen Branch voranschreitet. Das ist die realistische Situation in den meisten Unternehmen. Ein vollständiger Feature-Freeze für die Migrationsdauer ist selten durchsetzbar. Teams, die diesen Realismus in ihre Planung einbauen, schließen die Vue 3 Migration tatsächlich ab — Teams, die einen Feature-Freeze einplanen, scheitern meistens an der organisatorischen Durchsetzung.

9. Vue 2 vs. Vue 3: Kernunterschiede im Überblick

Die Unterschiede zwischen Vue 2 und Vue 3 sind tiefgreifender als ein API-Update. Die folgende Tabelle zeigt die wichtigsten Punkte für die Migrationsplanung.

Die größten Migration-Aufwände entstehen nicht durch die Vue-Kern-API, sondern durch das Ökosystem: Plugins, die Vue.prototype verwenden, Dekorator-basierte Klassen-Komponenten, und UI-Bibliotheken, die keine Vue-3-Version haben. Diese Punkte müssen in der Inventur-Phase vollständig identifiziert werden — nicht erst beim ersten Kompilierversuch mit Vue 3.

10. Zusammenfassung

Eine Vue 2 auf Vue 3 Migration ist kein Dependency-Update, sondern ein Migrationsprojekt mit eigenen Phasen, Risiken und Zeitbedarf. Die kritischen Erfolgsfaktoren: eine vollständige Inventur vor dem ersten Code-Change, realistische Zeitplanung, die den parallelen Produktionsbetrieb einschließt, und die Identifikation der wirklichen Blocker — meistens Plugins und UI-Bibliotheken, nicht die Vue-Kern-API. Der Vue Migration Build ist ein wertvolles Analyse-Werkzeug, aber keine dauerhafte Lösung.

Die Composition API muss nicht sofort für alle Komponenten eingesetzt werden — die Options API bleibt in Vue 3 vollständig unterstützt. Pinia ist die langfristig bessere Wahl als Vuex 4, aber die Migration kann schrittweise erfolgen. Tests brauchen eigene Migrationszeit — @vue/test-utils v2 hat Breaking Changes, die unterschätzt werden. Mit einem ehrlichen Zeitplan, der diese Faktoren berücksichtigt, schließen Teams ihre Vue Migration ab — ohne die Last-Minute-Überraschungen, die entstehen, wenn man die Komplexität zu Beginn unterschätzt.

11. FAQ: Vue 2 auf Vue 3 migrieren