February 14, 2026Tuemedia IT Solutions

Nuxt 5MigrationUpgradeStrategyBest PracticesDevOps

Migration Guide - So bereitest du dich auf Nuxt 5 vor (ohne Drama)

Ein typischer Moment in jedem Team:

„Wann upgraden wir auf Nuxt 5?"

Die drei typischen Reaktionen:

Entwickler A:
„Sofort! Ich will die neuen Features!"

Entwickler B:
„Lieber warten, bis es stable ist."

Projektleiter:
„Wie lange dauert das? Und was kann kaputtgehen?"

Die ehrliche Antwort:

Es kommt drauf an.

Auf:

die Größe deines Projekts
wie viel Custom Code du hast
wie gut deine Tests sind
wie dein Deployment aussieht

In diesem Artikel schauen wir uns an:

Wie du das Upgrade planst (Small Team vs. Enterprise)
Wie du testest, ohne Production zu riskieren
Welche Strategie wirklich funktioniert
Was du tun solltest, bevor Nuxt 5 überhaupt released ist

Die Upgrade-Strategie: Zwei kleine Sprünge statt einem großen

Das wichtigste zuerst:

Upgrade nicht direkt von Nuxt 3 → Nuxt 5.

Nuxt 5 setzt voraus, dass du die Nuxt 4 Struktur bereits nutzt.

Das bedeutet:

Der richtige Weg:

Nuxt 3 → Nuxt 4 (kleinerer Schritt)
Stabilisieren
Nuxt 4 → Nuxt 5 (größerer Schritt)

Der falsche Weg:

Nuxt 3 → Nuxt 5 direkt (= beide Changes auf einmal)

Warum?

Weil wenn etwas kaputtgeht, weißt du nicht:

War es ein Nuxt 4 Change? Oder ein Nuxt 5 Change?

Zwei getrennte Schritte = klarer Fehler-Ursache.

Phase 0: Vorbereitung (bevor du irgendwas machst)

Bevor du überhaupt anfängst zu upgraden:

1) Ist dein Projekt auf Nuxt 3 stable?

Klingt banal, aber:

Upgrade nur, wenn dein aktuelles Setup stable ist.

Wenn du aktuell noch Bugs hast, wird ein Upgrade sie nicht lösen.

Im Gegenteil:

Es wird neue Probleme dazuaddieren.

Checkliste:

Keine kritischen Bugs im Backlog
Tests laufen durch (falls vorhanden)
Production läuft stable
Keine laufenden großen Refactorings

2) Wie gut sind deine Tests?

Das ist der wichtigste Indikator für:

Wie schmerzfrei wird das Upgrade?

Test Coverage	Upgrade-Risiko
0% (keine Tests)	🔴 Hoch
30-50% (Unit Tests)	🟡 Mittel
70%+ (Unit + E2E)	🟢 Niedrig

Wenn du keine Tests hast:

Das Upgrade wird zur manuellen Testing-Party.

Jeder Flow muss manuell durchgeklickt werden.

Pragmatische Empfehlung:

Wenn du keine Tests hast, schreib zumindest E2E Tests für kritische Flows:

Login
Checkout
Wichtigste Business-Logik

Das spart dir Stunden beim Upgrade.

3) Dependencies checken

Viele Projekte haben Custom Dependencies:

Custom Nuxt Modules
Custom Plugins
alte integrations

Wichtig:

Checken, ob diese mit Nuxt 5 kompatibel sind.

# Check dependencies
npm outdated

# Check for deprecated packages
npm audit

Wenn du alte, unmaintained Packages hast:

Jetzt ist der Zeitpunkt, sie zu ersetzen.

4) Node Version überall sicherstellen

Das ist kritisch.

Nuxt 5 braucht Node 18+.

Das bedeutet:

Lokal (alle Entwickler)
CI/CD (GitHub Actions, GitLab CI, etc.)
Docker (Base Images)
Hosting (Vercel, Netlify, VPS, etc.)
Staging
Production

Checkliste:

Lokal: node -v (≥ 18)
.nvmrc erstellen (falls noch nicht vorhanden)
CI/CD Pipelines auf Node 18+ umstellen
Docker Image auf node:20-alpine oder ähnlich
Hosting-Plattform auf Node 18+ einstellen

Beispiel .nvmrc:

Das stellt sicher, dass alle Entwickler die gleiche Version nutzen.

💡 Mehr Details: Nitro v3 Breaking Changes

Phase 1: Upgrade zu Nuxt 4 (der kleinere Schritt)

Wenn Vorbereitung abgeschlossen:

Zuerst Nuxt 4.

Schritt 1: Dependencies upgraden

# Upgrade Nuxt zu v4
npm install nuxt@^4.0.0

# Upgrade related packages
npm install @nuxt/devtools@latest

# Check for breaking changes in other packages
npm outdated

Schritt 2: Build testen

npm run build

Wenn das durchläuft: gut.

Wenn nicht:

Fehler lesen und fixen.

Typische Fehler:

veraltete Nuxt Modules (updaten)
deprecated APIs (siehe Console Output)
TypeScript Fehler (strictere Types)

Schritt 3: Dev Server testen

npm run dev

App öffnen und manuell testen:

Startseite lädt
Navigation funktioniert
API Routes funktionieren
Auth funktioniert (falls vorhanden)

Schritt 4: Tests laufen lassen

npm run test

Wenn Tests durchlaufen: perfekt.

Wenn nicht: fixen.

Schritt 5: Funktionalität testen

Jetzt kommt der wichtige Teil:

Alle kritischen Flows durchgehen.

Das ist keine „5-Minuten-Sache".

Plan dafür mindestens 1-2 Stunden ein.

Checkliste (beispielhaft):

Schritt 6: Staging Deployment

Nicht direkt Production upgraden.

Erst Staging.

# Deploy to staging
npm run build
# ... deploy to staging environment

Dann nochmal alle Flows testen (auf Staging).

Warum?

Weil manchmal Dinge in Production-ähnlichen Environments anders laufen:

andere Environment Variables
andere Datenbank
andere API-Endpunkte
andere Caching-Layer

Schritt 7: Production Deployment

Wenn Staging stable ist:

Production deployen.

Wichtig:

Rollback-Plan haben (wie machst du Rollback, wenn's schiefgeht?)
Monitoring aktivieren (Error Tracking, Performance)
Staged Rollout (wenn möglich - z. B. 10% Traffic, dann 50%, dann 100%)

Schritt 8: Stabilisieren

Jetzt nicht sofort weiter zu Nuxt 5.

Erstmal stabilisieren.

Das bedeutet:

paar Tage (oder Wochen) auf Nuxt 4 laufen lassen
Monitoring checken
Fehlerrate checken
Performance checken

Wenn alles stable ist:

Dann zu Nuxt 5.

Phase 2: Upgrade zu Nuxt 5 (der größere Schritt)

Jetzt kommt der spannende Teil.

Achtung:

Nuxt 5 ist zum Zeitpunkt dieses Artikels noch nicht released.

Das bedeutet:

Dieser Teil ist Vorbereitung - nicht „jetzt sofort machen".

Pre-Release: Nightly Builds testen

Bevor Nuxt 5 überhaupt stable ist:

Teste Nightly Builds.

Das ist für größere Projekte extrem wertvoll.

Warum?

Weil du frühzeitig siehst:

was bricht
wie viel Aufwand die Migration ist
wo die Risiken liegen

Wie das geht:

# Install Nuxt 5 Nightly
npm install nuxt@nightly

# Try build
npm run build

# Try dev
npm run dev

Wichtig:

Das ist nicht für Production.

Das ist nur, um zu sehen:

„Was kommt auf uns zu?"

Wenn du Probleme siehst:

dokumentieren
ggf. Issue im Nuxt Repo aufmachen
alternative Lösungen überlegen

Wenn Nuxt 5 released ist: Migration starten

Schritt 1: Dependencies upgraden

# Upgrade to Nuxt 5
npm install nuxt@^5.0.0

# Check related packages
npm outdated

# Update if needed
npm update

Schritt 2: Breaking Changes fixen

Jetzt kommen die Nitro v3 Breaking Changes:

Wichtigste:

app.config.ts migrieren (zu runtimeConfig)
Cached Functions checken (SWR explizit machen)
Nitro Plugins anpassen (Parameter-Name)

💡 Mehr Details: Nitro v3 Breaking Changes

Beispiel: app.config.ts Migration

Alt (app.config.ts):

// app.config.ts
export default defineAppConfig({
  apiUrl: "https://api.example.com",
  apiKey: process.env.API_KEY,
  theme: "dark",
});

Neu (nuxt.config.ts):

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Private (server-only)
    apiKey: process.env.API_KEY,

    // Public (client + server)
    public: {
      apiUrl: "https://api.example.com",
      theme: "dark",
    },
  },
});

Beispiel: SWR explizit machen

Alt (implizit):

// server/api/data.ts
export default defineCachedEventHandler(
  async (event) => {
    return await fetchData();
  },
  {
    maxAge: 60,
  },
);

Neu (explizit):

// server/api/data.ts
export default defineCachedEventHandler(
  async (event) => {
    return await fetchData();
  },
  {
    maxAge: 60,
    swr: true, // ← explizit, falls gewünscht
  },
);

Schritt 3: Build & Dev testen

Gleicher Prozess wie bei Nuxt 4:

npm run build
npm run dev

Fehler fixen.

Schritt 4: Tests laufen lassen

npm run test

Falls Tests brechen:

rausfinden, warum
fixen
ggf. Tests anpassen (wenn Behavior sich geändert hat)

Schritt 5: Funktionalität testen

Wieder: alle kritischen Flows durchgehen.

Nicht überspringen.

Schritt 6: Neue Features nutzen (optional)

Jetzt hast du Zugriff auf:

Tasks API (Background Jobs)
Cron Scheduling
WebSockets

Falls du die nutzen willst:

Jetzt ist der Zeitpunkt.

💡 Mehr Details:

Schritt 7: Staging & Production Deployment

Gleicher Prozess wie bei Nuxt 4:

Staging deployen
Testen
Stabilisieren
Production deployen
Monitoring

Strategien je nach Projektgröße

Nicht jedes Projekt ist gleich.

Hier sind pragmatische Strategien je nach Größe:

Small Team / Solo Developer

Situation:

1-3 Entwickler
kleineres Projekt
keine dedizierten QA

Strategie:

Lokale Tests (manuell)
Staging Deployment
1-2 Tage warten
Production Deployment

Zeitaufwand: ~1-2 Tage

Risiko: Mittel (ohne Tests höher)

Medium Team / Startup

Situation:

5-15 Entwickler
SaaS-Produkt
echte User
moderate Tests

Strategie:

Feature Branch erstellen
Upgrade durchführen
Tests laufen lassen
Staging Deployment
QA testen lassen
1 Woche stabilisieren
Production Deployment (staged: 10% → 50% → 100%)

Zeitaufwand: ~1-2 Wochen

Risiko: Niedrig (mit Tests)

Enterprise / Large Team

Situation:

20+ Entwickler
Monorepo
viele Integrationen
Custom Modules
hohe Test Coverage

Strategie:

Nightly Builds testen (Wochen vor Release)
Migration Team bilden
Migration Plan erstellen (detailliert)
Dependencies auditieren
Custom Modules upgraden
Feature Branch mit Upgrade
Full Test Suite laufen lassen
Integration Tests
Staging Deployment
QA Phase (1-2 Wochen)
Beta User Testing (optional)
Production Rollout (sehr staged: 5% → 10% → 25% → 50% → 100%)

Zeitaufwand: ~1-2 Monate

Risiko: Sehr niedrig (mit umfassender Testing-Strategie)

Rollback-Plan: Wenn's schiefgeht

Das wichtigste bei jedem Upgrade:

Einen Rollback-Plan haben.

Fragen, die du beantworten musst:

Wie mache ich Rollback?
Wie lange dauert das?
Gibt es Datenbank-Migrationen, die rückgängig gemacht werden müssen?
Wie kommuniziere ich das (intern / extern)?

Vercel / Netlify

Rollback ist trivial:

Einfach vorheriges Deployment aktivieren
Dauert ~1 Minute

Docker / Kubernetes

Rollback ist standardisiert:

# Kubernetes
kubectl rollout undo deployment/nuxt-app

# Docker Compose
docker compose up -d --force-recreate

VPS / Traditional Server

Rollback ist manueller:

Git: vorherigen Commit auschecken
Dependencies: vorherige package-lock.json nutzen
Build: neu bauen
Server: neu starten

Plan dafür 10-30 Minuten ein.

Monitoring: Was du nach dem Upgrade checken solltest

Nach dem Upgrade:

Nicht einfach „vergessen".

Sondern: aktiv monitoren.

1) Error Rate

Schau in dein Error Tracking (Sentry, Rollbar, etc.):

Gibt es neue Fehler?
Steigt die Error Rate?
Gibt es spezifische Patterns?

Normal:

Error Rate bleibt gleich oder sinkt

Problem:

Error Rate steigt deutlich (> 20%)

→ Rollback oder Hotfix

2) Performance

Schau in dein APM (New Relic, DataDog, etc.):

Ist die App schneller oder langsamer?
Gibt es neue Bottlenecks?
Steigt die Server Load?

Normal:

Performance bleibt gleich oder wird besser (Nitro v3 ist schneller)

Problem:

Response Times steigen deutlich (> 50%)

→ Analyse & ggf. Rollback

3) User Feedback

Das ist oft der wichtigste Indikator:

Gibt es mehr Support-Tickets?
Melden User Probleme?
Gibt es spezifische Beschwerden?

Normal:

User merken nichts vom Upgrade

Problem:

Viele User melden Probleme

→ Analyse & Kommunikation

Kommunikation: Wie du das Team / User informierst

Upgrade ist nicht nur ein Tech-Thema.

Es ist auch ein Kommunikations-Thema.

Intern (Team)

Vor dem Upgrade:

„Wir upgraden nächste Woche auf Nuxt 5. Hier sind die wichtigsten Changes: .... Bitte testet eure Features vorher nochmal."

Während dem Upgrade:

„Upgrade läuft. Staging ist deployed. Bitte testen."

Nach dem Upgrade:

„Production ist upgraded. Bitte meldet Probleme sofort."

Extern (User)

Für kleine Projekte:

Meist nicht nötig, User zu informieren

Für größere SaaS:

Maintenance Window ankündigen (falls nötig)
Changelog veröffentlichen (neue Features erwähnen)
Status Page updaten (während Deployment)

Beispiel:

„Wir haben unsere Infrastruktur auf die neueste Version upgraded. Das bringt bessere Performance und neue Features. Falls du Probleme siehst, melde dich bitte."