Prompt zur Migration einer Next.js 14 App auf Next.js 16

Strukturierter KI-Agent-Prompt zur Migration eines Next.js 14 App Router Projekts auf Next.js 16 mit Behandlung von Breaking Changes und schrittweisem Vorgehen.

Verwenden Sie diesen Prompt für eine sorgfältige, schrittweise Migration von Next.js 14 zu 16 – unter Berücksichtigung der async params/searchParams API-Änderung, der React 19 Peer-Abhängigkeit und veralteter next/headers Muster vor dem Upgrade.

Haupt-Prompt

You are migrating an existing Next.js 14 App Router project to Next.js 16.

Do this in the following ordered steps — do not skip steps or combine them.

Step 1 — Audit (read-only):
  - List every file that uses `params` or `searchParams` as synchronous props.
  - List every file that calls `cookies()`, `headers()`, or `draftMode()` without `await`.
  - List every `next/image` usage with a deprecated prop (e.g., `layout`, `objectFit`).
  - List the current `peerDependencies` for React and React DOM.
  Output the audit as a plain list. Stop and wait for my review.

Step 2 — Update deps:
  - Run: `bun add next@16 react@19 react-dom@19 @types/react@19 @types/react-dom@19`
  - Do NOT change any source files in this step.

Step 3 — Fix async params:
  - For every Page, Layout, and `generateMetadata` function that receives `params` or
    `searchParams`, make the function `async` and `await` the prop before use.
  - Type the props as `Promise<{ slug: string }>` (or the relevant shape), not `{ slug: string }`.

Step 4 — Fix async dynamic APIs:
  - Add `await` before every call to `cookies()`, `headers()`, and `draftMode()`.
  - If the call is inside a non-async function, make that function async.

Step 5 — Fix deprecated Image props:
  - Remove `layout="fill"` and replace with `fill` (boolean).
  - Remove `objectFit` and `objectPosition` props and move them to a `className` or `style`.

Step 6 — Verify:
  - Run `bun run typecheck` and fix all remaining TypeScript errors.
  - Run `bun run build` and confirm exit 0.

After each step, show the diff and wait for confirmation before proceeding.

Implementierungshinweise

In Next.js 15+ sind params und searchParams in Promise eingewickelt. Ein synchroner Zugriff kompiliert zwar, führt aber zur Laufzeit zu einem Fehler – die Überprüfung in Schritt 1 ist vor dem Upgrade unerlässlich.
cookies() und headers() sind in Next.js 15+ asynchron; der häufigste Fehler besteht darin, sie innerhalb einer Funktion aufzurufen, die nicht als async markiert ist.
React 19 entfernt einige veraltete APIs (defaultProps bei Funktionskomponenten, String-Refs). Führen Sie zwischen den Schritten bun run typecheck aus, um diese frühzeitig zu erkennen.

Erwartete Dateiänderungen

package.json                          (edited — next, react, react-dom versions)
bun.lock / package-lock.json          (edited automatically)
src/app/**/page.tsx                   (edited — async params)
src/app/**/layout.tsx                 (edited — async params)
src/app/**/generateMetadata           (edited — async params)
src/components/**/*.tsx               (edited — deprecated Image props)

Abnahmekriterien

bun run typecheck beendet sich nach allen Schritten mit Exit-Code 0.
bun run build beendet sich ohne Warnungen zu veralteten APIs mit Exit-Code 0.
Alle dynamischen Routen werden in bun run dev korrekt gerendert.
Keine params- oder searchParams-Prop wird synchron zugegriffen.

Testbefehle

bun run typecheck
bun run build
bun run dev
# visit several dynamic routes and confirm no runtime errors
grep -r "layout=\"fill\"" src/ && echo "FAIL: deprecated Image prop found"
grep -rn "cookies()\|headers()\|draftMode()" src/ | grep -v "await" && echo "WARN: unawaited dynamic API"

Häufige KI-Fehler

Überspringen des Überprüfungsschritts und Vornehmen aller Änderungen in einem Durchgang, was zu schwer nachvollziehbaren Fehlern führt.
Typisierung von async params als { params: { slug: string } } anstelle von { params: Promise<{ slug: string }> }.
Vergessen, @types/react zusammen mit react zu aktualisieren, was Typinkonsistenzen hinterlässt.
Nicht-Abwarten von cookies() innerhalb einer verschachtelten Hilfsfunktion, die selbst nicht asynchron ist.

Fix-Prompt

The build fails with type errors on params or a runtime error about cookies/headers.
Fix in order:
1. For any page or layout receiving `params`, update the prop type to `Promise<{ slug: string }>` and
   add `const { slug } = await params;` at the top of the function body.
2. Find every call to `cookies()`, `headers()`, `draftMode()` not preceded by `await` and add it.
   Make the containing function async if it isn't already.
3. Run `bun run typecheck` and show me only the remaining errors.