{
  "id": "migrate-nextjs-14-to-16",
  "type": "prompts",
  "category": "prompts",
  "locale": "de",
  "url": "/de/prompts/migrate-nextjs-14-to-16",
  "title": "Prompt zur Migration einer Next.js 14 App auf Next.js 16",
  "description": "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.",
  "tools": [
    "Cursor",
    "Claude Code",
    "Codex",
    "Windsurf"
  ],
  "stack": [
    "Next.js",
    "TypeScript"
  ],
  "tags": [
    "nextjs",
    "typescript",
    "migrate"
  ],
  "difficulty": "hard",
  "updated": "2026-06-08",
  "markdown": "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.\n\n## Haupt-Prompt\n\n```txt title=\"Main Prompt\"\nYou are migrating an existing Next.js 14 App Router project to Next.js 16.\n\nDo this in the following ordered steps — do not skip steps or combine them.\n\nStep 1 — Audit (read-only):\n  - List every file that uses `params` or `searchParams` as synchronous props.\n  - List every file that calls `cookies()`, `headers()`, or `draftMode()` without `await`.\n  - List every `next/image` usage with a deprecated prop (e.g., `layout`, `objectFit`).\n  - List the current `peerDependencies` for React and React DOM.\n  Output the audit as a plain list. Stop and wait for my review.\n\nStep 2 — Update deps:\n  - Run: `bun add next@16 react@19 react-dom@19 @types/react@19 @types/react-dom@19`\n  - Do NOT change any source files in this step.\n\nStep 3 — Fix async params:\n  - For every Page, Layout, and `generateMetadata` function that receives `params` or\n    `searchParams`, make the function `async` and `await` the prop before use.\n  - Type the props as `Promise<{ slug: string }>` (or the relevant shape), not `{ slug: string }`.\n\nStep 4 — Fix async dynamic APIs:\n  - Add `await` before every call to `cookies()`, `headers()`, and `draftMode()`.\n  - If the call is inside a non-async function, make that function async.\n\nStep 5 — Fix deprecated Image props:\n  - Remove `layout=\"fill\"` and replace with `fill` (boolean).\n  - Remove `objectFit` and `objectPosition` props and move them to a `className` or `style`.\n\nStep 6 — Verify:\n  - Run `bun run typecheck` and fix all remaining TypeScript errors.\n  - Run `bun run build` and confirm exit 0.\n\nAfter each step, show the diff and wait for confirmation before proceeding.\n```\n\n## Implementierungshinweise\n\n- 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.\n- `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.\n- 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.\n\n## Erwartete Dateiänderungen\n\n```txt\npackage.json                          (edited — next, react, react-dom versions)\nbun.lock / package-lock.json          (edited automatically)\nsrc/app/**/page.tsx                   (edited — async params)\nsrc/app/**/layout.tsx                 (edited — async params)\nsrc/app/**/generateMetadata           (edited — async params)\nsrc/components/**/*.tsx               (edited — deprecated Image props)\n```\n\n## Abnahmekriterien\n\n- `bun run typecheck` beendet sich nach allen Schritten mit Exit-Code 0.\n- `bun run build` beendet sich ohne Warnungen zu veralteten APIs mit Exit-Code 0.\n- Alle dynamischen Routen werden in `bun run dev` korrekt gerendert.\n- Keine `params`- oder `searchParams`-Prop wird synchron zugegriffen.\n\n## Testbefehle\n\n```bash\nbun run typecheck\nbun run build\nbun run dev\n# visit several dynamic routes and confirm no runtime errors\ngrep -r \"layout=\\\"fill\\\"\" src/ && echo \"FAIL: deprecated Image prop found\"\ngrep -rn \"cookies()\\|headers()\\|draftMode()\" src/ | grep -v \"await\" && echo \"WARN: unawaited dynamic API\"\n```\n\n## Häufige KI-Fehler\n\n- Überspringen des Überprüfungsschritts und Vornehmen aller Änderungen in einem Durchgang, was zu schwer nachvollziehbaren Fehlern führt.\n- Typisierung von async params als `{ params: { slug: string } }` anstelle von `{ params: Promise<{ slug: string }> }`.\n- Vergessen, `@types/react` zusammen mit `react` zu aktualisieren, was Typinkonsistenzen hinterlässt.\n- Nicht-Abwarten von `cookies()` innerhalb einer verschachtelten Hilfsfunktion, die selbst nicht asynchron ist.\n\n## Fix-Prompt\n\n```txt title=\"Fix Prompt\"\nThe build fails with type errors on params or a runtime error about cookies/headers.\nFix in order:\n1. For any page or layout receiving `params`, update the prop type to `Promise<{ slug: string }>` and\n   add `const { slug } = await params;` at the top of the function body.\n2. Find every call to `cookies()`, `headers()`, `draftMode()` not preceded by `await` and add it.\n   Make the containing function async if it isn't already.\n3. Run `bun run typecheck` and show me only the remaining errors.\n```"
}