Prompt-to-PR: Next.js 14 auf 16 migrieren

Next.js 16 bringt React 19, asynchrone params und searchParams, überarbeitetes Fetch-Caching und Turbopack als Standard-Dev-Bundler. Dieses Playbook hält den Agenten auf die Breaking Changes fokussiert und verhindert, dass er funktionierenden Code umschreibt.

1. Anforderung

Aktualisieren Sie next von 14.x auf 16.x (und react/react-dom auf 19.x) ohne Funktionsrückschritte. Behandeln Sie jeden Breaking Change, der durch den offiziellen Codemod aufgedeckt wird, sowie alle verbleibenden Probleme, die nicht davon erfasst werden.

2. Erster Prompt

Migrate this project from Next.js 14 to Next.js 16. Follow these steps exactly.

Step 1 — run the official codemod:
  npx @next/codemod@latest upgrade latest --yes

Step 2 — manual fixes the codemod does not cover:
  a. `params` and `searchParams` in page.tsx/layout.tsx files are now Promises.
     Await them: `const { id } = await params;`
     Do NOT destructure params in the function signature.
  b. `cookies()`, `headers()`, `draftMode()` are now async.
     Add `await` before every call.
  c. `fetch()` is no longer cached by default in Route Handlers.
     Where caching is intentional, add `{ next: { revalidate: N } }`.
  d. Remove any `export const dynamic = 'force-dynamic'` that is now the default.
  e. Replace `<Image>` with the new `onLoad` prop signature if present.

Step 3 — update package.json:
  "next": "^16.0.0"
  "react": "^19.0.0"
  "react-dom": "^19.0.0"
  "@types/react": "^19.0.0"
  "@types/react-dom": "^19.0.0"

Do not change any business logic, UI, or database code.
List every file you changed and why.

3. Erwartete Dateiänderungen

package.json                          (next, react, react-dom, @types/react*)
src/app/**/page.tsx                   (await params / searchParams)
src/app/**/layout.tsx                 (await params where used)
src/app/api/**/route.ts               (await cookies/headers; fetch cache opts)
src/middleware.ts                     (if it uses deprecated config keys)
next.config.ts                        (remove deprecated options)

4. Überprüfungsliste

• package.json setzt next auf ^16.0.0 und React auf ^19.0.0.
• Jede Seite/jedes Layout, das params destrukturiert, wartet jetzt zuerst darauf.
• Keine synchronen cookies()- oder headers()-Aufrufe verbleiben in Serverkomponenten.
• fetch-Aufrufe, die zuvor auf implizites Caching angewiesen waren, haben jetzt eine explizite revalidate- oder no-store-Option.
• next.config.ts enthält keine veralteten Schlüssel experimental.appDir oder swcMinify.
• TypeScript kompiliert mit bun tsc --noEmit — null Fehler.
• Der Agent hat keine UI-Komponenten oder Geschäftslogik umgeschrieben.

5. Testbefehle

# Install updated deps
bun install

# Type-check
bun tsc --noEmit

# Dev build (Turbopack default in Next.js 16)
bun dev

# Production build — catches async-params errors at compile time
bun run build

# Run existing test suite
bun test

6. Häufige Fehler

• params.id vor await verwendet — TypeScript-Fehler: Property 'id' does not exist on type 'Promise<...>'. Der Agent wartet manchmal in einer Datei auf params, in einer anderen nicht.
• cookies() nicht awaited — Laufzeitfehler: cookies() was called outside of a Server Component. Fügen Sie await hinzu.
• Turbopack inkompatibles webpack-Plugin — next dev meldet Fehler bei einer benutzerdefinierten webpack()-Konfiguration. Turbopack ignoriert webpack-Plugins; migrieren Sie sie oder schalten Sie sie bedingt aus.
• @types/react-Versionskonflikt — Peer-Abhängigkeitskonflikt zwischen alten Komponentenbibliotheken und React 19-Typen. Fixieren Sie @types/react auf 19 und überschreiben Sie ggf.
• useFormState entfernt — ersetzt durch useActionState aus react. Der Codemod fängt dies normalerweise ab, aber bestätigen Sie.

7. Fehlerbehebung-Prompt

TypeScript reports: "Property 'slug' does not exist on type
'Promise<{ slug: string }>'" in src/app/blog/[slug]/page.tsx.

The page function signature must be:
  export default async function Page({ params }: { params: Promise<{ slug: string }> })

Then at the top of the function body:
  const { slug } = await params;

Apply the same fix to every other page or layout that destructures params
without awaiting. List every file changed.

8. PR-Beschreibung

## Chore: Migrate Next.js 14 → 16 + React 19

**Breaking changes addressed**:
- `params` / `searchParams` are now `Promise`s — awaited in all pages/layouts
- `cookies()` / `headers()` are now async — awaited in all Server Components
- Fetch caching defaults changed — explicit `revalidate` added where needed
- Removed deprecated `next.config.ts` keys (`swcMinify`, `experimental.appDir`)

**Tooling**: dev server now uses Turbopack by default (`next dev --turbopack`).

Run `bun run build` to confirm zero type errors before merging.