# 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.

**Type:** Prompt  
**Tools:** Cursor, Claude Code, Codex, Windsurf  
**Stack:** Next.js, TypeScript  
**Difficulty:** hard  
**Updated:** 2026-06-08

---

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

```txt title="Main 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

```txt
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

```bash
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

```txt title="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.
```