Next.js Pages Router zu App Router: Praxisleitfaden mit Migrationsstrategie und Fallen-Checkliste

Der Tech Lead stellte in der Besprechung die Frage: „Können wir unser Next.js-12-Projekt auf 14 heben?“

Ich starrte auf den zwei Jahre alten Code – beim letzten React-17-Upgrade hatten wir eine Woche lang Bugs gefixt, der Support war am Limit.

Diesmal wirkte es anders. Abends in der Doku: App Router, Server Components, verschachtelte Layouts, bessere Performance – verlockend. Dann die Migrationsseite: API-Vergleichstabellen, getServerSideProps, _app.js aufteilen – Kopfschmerzen.

Noch unangenehmer: Die offizielle „schrittweise Migration“ klingt gut, aber beim Wechsel zwischen /pages und /app sehen Nutzer Loading-Spinner – die UX wird schlechter, nicht besser.

Zwei Wochen Fallen, Community-Threads und verschiedene Ansätze später hatte ich eine Strategie, der ich vertraue. In diesem Artikel teile ich:

• Wie Sie einschätzen, ob sich die Migration lohnt
• Zwei Strategien mit echten Vor- und Nachteilen (nicht nur Theorie aus der Doku)
• getServerSideProps Schritt für Schritt mit Code
• Sieben Fallen, in die ich selbst getappt bin – und wie Sie sie vermeiden

Wenn Sie unsicher sind oder mitten in der Migration hängen, soll Ihnen das ein paar Umwege ersparen.

Warum migrieren? Erst die Rechnung aufmachen

Nicht jedes Projekt lohnt den Aufwand.

Ein Bekannter fragte, ob ihre bald endende Kampagnen-Site auf den App Router soll. Mein Rat: nein – Code, der in sechs Monaten weg ist, braucht kein Upgrade.

Wann lohnt es sich? Meine Kriterien:

Bedarf an verschachtelten Layouts

Das war bei uns der Hauptgrund. Unser SaaS-Backend: Sidebar, Top-Nav, Content – drei Ebenen. Im Pages Router renderte die Sidebar bei jedem Seitenwechsel komplett neu.

Nutzer spürten ein Flackern – nicht langsames Netz, sondern Layout-Neuzeichnung.

Verschachtelte Layouts im App Router lösen das. WorkOS berichtet von „deutlich besserem Login ohne Loading oder Layout-Jitter“ – bei uns passt das: nur der Content-Bereich aktualisiert sich, die Navigation bleibt stabil.

Performance-Potenzial

First Paint über drei Sekunden? Der App Router kann helfen.

Unsere Produktliste nutzte früher getServerSideProps – jeder Refresh wartete auf das komplette serverseitige HTML. Mit Server Components streamen wir Listendaten vom Server; First Paint von 3,2 s auf 1,8 s.

Aber: Nicht jede Seite wird schneller. Rein clientseitige Interaktion (z. B. Canvas-Editor) profitiert kaum – manchmal wird es durch eine zusätzliche Abstraktionsschicht etwas langsamer.

Langfristige Wartung

Projekt drei Jahre oder länger? Früher migrieren, früher profitieren. Vercel stellt neue Features primär für den App Router bereit; der Pages Router ist im Wartungsmodus.

Ich wollte nicht in zwei Jahren erneut migrieren – mit dann vielleicht wieder anderen APIs und mehr Fallen.

Wann ich abrate

• Projekt geht bald offline – unnötiger Aufwand
• Kleine statische Site (≤5 Seiten) – Nutzen zu gering
• Team kennt React 18 noch nicht – erst Suspense und Server Components verstehen
• Viele alte Drittanbieter-Bibliotheken – Kompatibilitätsprobleme warten

Kernbotschaft: Nicht migrieren um der Migration willen. Welches konkrete Problem löst der Wechsel? Wenn die Antwort „keins, nur Neugier“ ist – lieber warten.

Unsere Rechnung: zwei Wochen Aufwand für bessere UX und weniger Technikschulden über drei Jahre – für uns stimmig. Wie sieht es bei Ihrem Projekt aus?

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Zwei Migrationsstrategien im Vergleich

Die Doku empfiehlt „schrittweise Migration“ – langsam, Seite für Seite.

In der Praxis hat das einen harten Nachteil.

Die Falle der schrittweisen Migration

Szenario: Startseite liegt unter /app, Produktdetail noch unter /pages. Nutzer klickt von der Startseite ins Detail – weißer Bildschirm, Spinner, dann Inhalt.

Grund: Wechsel zwischen App Router und Pages Router – für Next.js zwei getrennte Welten; das JavaScript-Bundle muss neu geladen werden. UX wie vor zehn Jahren.

WorkOS formuliert es so: Navigation zwischen Routern fühlt sich an wie ein Sprung zwischen zwei unabhängigen Apps. Sie wollten schrittweise migrieren – und haben es aufgegeben.

Ist schrittweise also unmöglich? Nein.

Passt gut, wenn:

• Seiten wenig gekoppelt sind (z. B. Blog)
• Sie ganze Module auf einmal migrieren (zuerst User-Bereich, dann Shop)
• Loading beim Router-Wechsel akzeptabel ist

Bei einem Tech-Blog habe ich das gesehen – ok. Bei SaaS oder E-Commerce würde ich es meiden.

WorkOS Zero-Downtime-Ansatz

Für komplexe Projekte: Seiten unter /app/new neu bauen, Versionswechsel per Query-Parameter.

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/:path*',
        destination: '/new/:path*',
        has: [
          {
            type: 'query',
            key: 'new',
            value: 'true',
          },
        ],
      },
    ]
  },
}

Normale Nutzer sehen unter /dashboard die alte Version; mit ?new=true die neue.

QA, Produkt und Design testen produktiv – Nutzer merken nichts. Wenn alles steht: /app/new nach /app, /pages löschen, fertig.

So haben wir es gemacht. Kein User-Bug vor dem Go-Live – eine Woche mit echten Daten getestet.

Ablauf:

1. Next.js 14 upgraden – /pages vorerst unangetastet
2. Routing-Hooks migrieren – next/router → next/navigation, Kompatibilität mit beiden Routern
3. Verzeichnis /app/new – Seitenstruktur dort neu
4. Bestehende Komponenten wiederverwenden – aus /pages importieren, nicht alles neu schreiben
5. rewrites konfigurieren – wie oben, Umschalten mit ?new=true
6. Intern testen + Canary – Team auf neuer Version, Bugs fixen
7. Produktiv – /app/new → /app, rewrites und /pages entfernen

Bei uns: zehn Arbeitstage – sechs Tage Seiten, drei Tage Bugs, ein Tag Launch.

Meine Empfehlung

• Weniger als 10 Seiten, geringe Kopplung → schrittweise
• Mehr als 10 Seiten, hohe UX-Anforderungen → Zero-Downtime
• Neues Projekt → direkt App Router

Feature-Entwicklung parallel zur Migration habe ich probiert – zwei Code-Stile, unangenehm. Entweder zwei Wochen fokussiert migrieren – oder noch warten.

getServerSideProps in der Praxis migrieren

Die häufigste Frage: „getServerSideProps gibt es nicht mehr – wie hole ich Daten?“

Im App Router ist es oft einfacher – mit anderem Denkmodell.

Von „getrennt“ zu „zusammen“

Pages Router: Datenschicht (getServerSideProps) und UI getrennt; Next.js ruft die Datenfunktion serverseitig auf und übergibt props.

App Router: Die Seitenkomponente ist async und lädt selbst:

// ❌ Alt: pages/project/[id].tsx
export async function getServerSideProps(context) {
  const { id } = context.params
  const res = await fetch(`https://api.example.com/projects/${id}`)
  const project = await res.json()

  return {
    props: { project }
  }
}

export default function ProjectPage({ project }) {
  return <h1>{project.title}</h1>
}

// ✅ Neu: app/project/[id]/page.tsx
export default async function ProjectPage({ params }) {
  const { id } = params
  const res = await fetch(`https://api.example.com/projects/${id}`, {
    cache: 'no-store' // Wichtig – entspricht getServerSideProps
  })
  const project = await res.json()

  return <h1>{project.title}</h1>
}

Zwei große Fallen folgen sofort.

Falle 1: Falsche Cache-Konfiguration

Standard: fetch im App Router ist gecacht (wie getStaticProps), nicht bei jedem Request frisch.

Bei uns blieb der Produktpreis nach der Migration stehen – Nutzer beschwerten sich über veraltete Preise. Ursache: Cache.

Merktabelle:

• getServerSideProps → cache: 'no-store'
• getStaticProps → cache: 'force-cache' (Standard)
• getStaticProps + revalidate → next: { revalidate: 60 }

Falle 2: Client-State

Seiten mit getServerSideProps hatten oft Filter, Sortierung – Client-State.

Problem: async Server Components dürfen kein useState, useEffect usw.

Lösung: Komponenten trennen.

// app/products/page.tsx (Server Component)
export default async function ProductsPage() {
  const products = await fetchProducts() // Server

  return <ProductList initialData={products} /> // an Client Component
}

// components/ProductList.tsx (Client Component)
'use client' // Diese Zeile!

import { useState } from 'react'

export function ProductList({ initialData }) {
  const [products, setProducts] = useState(initialData)
  const [filter, setFilter] = useState('')

  // Client-Filter
  const filtered = products.filter(p => p.name.includes(filter))

  return (
    <div>
      <input value={filter} onChange={e => setFilter(e.target.value)} />
      {filtered.map(p => <ProductCard key={p.id} product={p} />)}
    </div>
  )
}

Server lädt Daten, Client übernimmt Interaktion – klar getrennt.

Nicht die ganze Seite mit "use client" markieren – dann verlieren Server Components ihren Sinn.

Praktische Migrationsschritte

Schritt 1: Komponenten trennen
Noch in /pages: reine Darstellung vs. Stateful – testen.

Schritt 2: Nach /app verschieben

• Darstellung → app/[route]/page.tsx, async, Daten dort laden
• Stateful → eigene Datei mit "use client"
• getServerSideProps entfernen

Vorteil: Schnelles Rollback, wenn etwas schiefgeht.

Cookies und Header

Früher context.req.cookies – jetzt:

import { cookies } from 'next/headers'

export default async function Page() {
  const cookieStore = cookies()
  const token = cookieStore.get('auth-token')

  // Token für User-Daten nutzen...
}

Analog: headers(), redirect() aus next/headers bzw. next/navigation – vollständige Liste in der offiziellen Doku.

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

Sieben häufige Fallen und Lösungen

Diese sieben habe ich alle selbst erlebt – jeweils mindestens eine Stunde Debug.

Falle 1: Serverfehler verschwinden

Symptom: Seite rendert nicht, kein Fehler in der Konsole – Loading-Skeleton oder Leerseite.

Bei uns: API geändert, Seite leer. Kein Fehler in der Konsole. Ohne error.tsx schluckt Next.js den Serverfehler und zeigt Suspense-Fallback.

Lösung: error.tsx pro Route:

// app/dashboard/error.tsx
'use client'

export default function Error({ error, reset }) {
  return (
    <div>
      <h2>Fehler: {error.message}</h2>
      <button onClick={reset}>Erneut versuchen</button>
    </div>
  )
}

In der Entwicklung: Stacktrace. In Produktion: verständliche Meldung.

Falle 2: useRouter „funktioniert nicht“

Symptom: useRouter().push() navigiert nicht oder Methoden fehlen.

Ursache: next/router und next/navigation sind verschiedene APIs.

// ❌ Falsch gedacht
import { useRouter } from 'next/navigation'

const router = useRouter()
router.push('/dashboard') // push existiert – Verhalten anders!

Besser oft die Link-Komponente:

// ✅ Praxis
import { useRouter, usePathname, useSearchParams } from 'next/navigation'

const router = useRouter()
router.push('/dashboard') // geht, aber Link ist oft klarer

import Link from 'next/link'
<Link href="/dashboard">Zum Dashboard</Link>

Spickzettel:

Falle 3: Dynamic Import bricht

Symptom: next/dynamic rendert nicht – Fehler zu useState nur in Client Components.

Ursache: Server Components rendern serverseitig; client-only Bibliotheken (Charts) scheitern.

// ❌ Fehler
import dynamic from 'next/dynamic'

const Chart = dynamic(() => import('./Chart'), { ssr: false })

export default function Page() {
  return <Chart data={data} />
}

Chart braucht window – auf dem Server nicht vorhanden.

Lösung: page.tsx als Client Component – oder Chart in Client Component auslagern:

// app/charts/page.tsx
import { ClientChart } from './ClientChart'

export default function Page() {
  return <ClientChart />
}

// app/charts/ClientChart.tsx
'use client'

import dynamic from 'next/dynamic'

const Chart = dynamic(() => import('./Chart'), { ssr: false })

export function ClientChart() {
  return <Chart data={data} />
}

Falle 4: Flackern beim Seitenwechsel

Symptom: Link-Klick – ganze Seite neu, Header und Sidebar flackern.

Ursache: Kein oder falsches layout.tsx; Navigation in jeder page.tsx.

Richtig:

// app/layout.tsx (Root – alle Seiten)
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Header /> {/* Top-Nav – bleibt stabil */}
        {children}
      </body>
    </html>
  )
}

// app/dashboard/layout.tsx
export default function DashboardLayout({ children }) {
  return (
    <div className="flex">
      <Sidebar /> {/* Sidebar bleibt beim Wechsel innerhalb Dashboard */}
      <main>{children}</main>
    </div>
  )
}

Wechsel zwischen /dashboard/analytics und /dashboard/settings – nur main aktualisiert sich.

Falle 5: 404 greift nicht

Symptom: Eigene 404 erscheint nicht – Next.js-Standard.

Ursache: /pages/404.js kollidiert mit app/not-found.tsx.

Lösung: /pages/404.js und /pages/500.js löschen:

// app/not-found.tsx
export default function NotFound() {
  return <h1>Seite nicht gefunden</h1>
}

404 aus der Seite auslösen:

import { notFound } from 'next/navigation'

export default async function Page({ params }) {
  const data = await fetchData(params.id)

  if (!data) {
    notFound()
  }

  return <div>{data.title}</div>
}

Falle 6: Dev-Server wird immer langsamer

Symptom: Start ok, nach einigen Edits HMR 10 Sekunden, dann Absturz.

Ehrlich: Keine perfekte Lösung.

Bekanntes Next.js-14-Problem – FlightControl schreibt vom Dev-Server so schlecht, dass sie fast alle neuen Features dafür aufgeben würden; Neustart alle 20 Minuten.

Workarounds:

• Dev-Server regelmäßig neu starten (bei mir alle 15 Minuten)
• next dev --turbo (Turbopack – schneller, gelegentliche Bugs)
• Unnötige Server Components reduzieren – manche Seiten sind als Client Component sinnvoller

Next.js 15 soll hier besser werden – noch nicht im Detail getestet.

Falle 7: Drittanbieter-Bibliotheken

Symptom: Framer Motion, Lottie – window oder document fehlt.

Ursache: Rein clientseitige Bibliotheken in Server Components.

Lösung:

1. Betroffene Komponenten mit "use client"
2. Neuere Versionen mit React-18-Support prüfen
3. Notfalls SSR-fähige Alternative

Häufig client-only:

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

• Framer Motion (Exit-Animationen – offene Issues)
• swiper, slick-carousel
• ECharts, Chart.js
• react-dnd, dnd-kit

Bei starker Abhängigkeit vorher GitHub-Issues lesen.

Optimierung nach der Migration

Migration ist nicht das Ende.

Weniger Client-JavaScript

Stärke der Server Components.

Unsere Produktliste: früher ~120 KB React (gzip). Nach Migration: Darstellung serverseitig, Filter/Sortierung clientseitig – ~45 KB.

Prüfen:

npm run build

Build-Ausgabe: (Static) / (SSR) vs. ○ (Client Component). Viele ○ → zu viel "use client".

Tipps:

• Statischer Inhalt → Server Component
• Formulare, Buttons → Client Component
• Nicht die ganze Seite clientseitig – nur betroffene Kinder

Cache sinnvoll nutzen

Im App Router feiner als im Pages Router.

// Kein Cache – Echtzeitdaten
fetch(url, { cache: 'no-store' })

// 60 s Cache, dann Revalidierung
fetch(url, { next: { revalidate: 60 } })

// Dauerhaft – statische Daten
fetch(url, { cache: 'force-cache' })

Produktliste: 60 s revalidate – Daten frisch genug, API-Last −60 %.

Performance messen

Vorher/Nachher:

• FCP – erstes sichtbares Content-Fragment
• TTI – Seite voll interaktiv
• CLS – Layout-Verschiebung beim Laden

Mit Vercel Analytics: FCP 3,2 s → 1,8 s, TTI 5,1 s → 3,3 s.

Nicht jede Seite wird schneller – Canvas-Editor bei uns praktisch unverändert.

Nicht überoptimieren

Nicht jede Komponente für Server Components zerlegen.

Ich habe ein Formular in 20 Mini-Komponenten geteilt – Lesbarkeit runter, Wartung teurer.

Faustregel: Braucht die Komponente useState/useEffect → "use client". Server Components sind Werkzeug, kein KPI.

Fazit

Migration ist kein Trend – sie löst echte Probleme: verschachtelte Layouts, weniger Client-JS, langfristige Wartbarkeit.

Strategie passend wählen: klein und schrittweise, groß Zero-Downtime. Parallel neue Features und Migration vermeiden.

Fallen sind normal – die sieben hier sind die Spitze des Eisbergs. GitHub-Issues durchsuchen; die meisten Probleme kennt jemand schon.

Lesbarkeit vor Bundle-Größe – Team und Codequalität zählen.

Pilot: 1–2 Seiten, Prozess verstehen, dann skalieren. Bei uns: erste Seite drei Tage, die nächsten zehn fünf Tage.

Der App Router hat Schwächen (Dev-Server!), die Richtung stimmt. Mit reiferem Ökosystem werden viele Fallen verschwinden.

Wenn Sie unterwegs hängen – melden Sie sich; vielleicht kenne ich die gleiche Falle.

Weiterführend:

• Offizielle Next.js-Migrationsanleitung
• WorkOS Zero-Downtime-Migration
• App Router FAQ (GitHub Discussions)

Viel Erfolg bei der Migration!