Prompt para migrar una app de Next.js 14 a Next.js 16

Prompt estructurado de agente de IA para migrar un proyecto de Next.js 14 App Router a Next.js 16 con manejo de cambios disruptivos y pasos incrementales.

Usa este prompt para guiar una migración cuidadosa e incremental de Next.js 14 a 16 — manejando el cambio de API asíncrona de params/searchParams, la dependencia de React 19 y los patrones obsoletos de next/headers antes de actualizar.

Prompt principal

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.

Notas de implementación

En Next.js 15+, params y searchParams están envueltos en Promise. Acceder a ellos de forma síncrona compilará pero fallará en tiempo de ejecución — la auditoría en el Paso 1 es esencial antes de actualizar.
cookies() y headers() son asíncronos en Next.js 15+; el modo de fallo más común es llamarlos dentro de una función que no está marcada como async.
React 19 elimina algunas APIs heredadas (defaultProps en componentes de función, refs de cadena). Ejecuta bun run typecheck entre cada paso para detectarlas temprano.

Cambios de archivo esperados

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)

Criterios de aceptación

bun run typecheck sale con código 0 después de todos los pasos.
bun run build sale con código 0 sin advertencias sobre APIs obsoletas.
Todas las rutas dinámicas se renderizan correctamente en bun run dev.
Ninguna prop params o searchParams se accede de forma síncrona.

Comandos de prueba

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"

Errores comunes de la IA

Saltarse el paso de auditoría y hacer todos los cambios en una sola pasada, causando errores difíciles de rastrear.
Tipificar params asíncronos como { params: { slug: string } } en lugar de { params: Promise<{ slug: string }> }.
Olvidar actualizar @types/react junto con react, dejando incompatibilidades de tipos.
No hacer await a cookies() dentro de una función helper anidada que a su vez no es async.

Prompt de corrección

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.