Prompt-to-PR: Migrar de Next.js 14 a 16

Next.js 16 incluye React 19, params y searchParams asíncronos, una revisión del almacenamiento en caché de fetch, y Turbopack como bundler de desarrollo predeterminado. Este manual mantiene al agente enfocado en los cambios disruptivos y evita que reescriba código funcional.

1. Requisito

Actualiza next de 14.x a 16.x (y react/react-dom a 19.x) sin regresiones de funcionalidad. Aborda todos los cambios disruptivos que surjan del codemod oficial y cualquier problema residual que no haya sido detectado.

2. Primer 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. Cambios de archivos esperados

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. Lista de verificación

• package.json fija next en ^16.0.0 y React en ^19.0.0.
• Cada página/layout que desestructure params ahora lo espera primero.
• No quedan llamadas síncronas a cookies() o headers() en Server Components.
• Las llamadas fetch que antes dependían del almacenamiento en caché implícito ahora tienen una opción explícita revalidate o no-store.
• next.config.ts no tiene las claves obsoletas experimental.appDir ni swcMinify.
• TypeScript compila con bun tsc --noEmit — cero errores.
• El agente no reescribió ningún componente de UI ni lógica de negocio.

5. Comandos de prueba

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

• params.id usado antes de await — Error de TypeScript: Property 'id' does not exist on type 'Promise<...>'. A veces el agente hace await de params en un archivo y en otro no.
• cookies() sin await — Error en tiempo de ejecución: cookies() was called outside of a Server Component. Agrega await.
• Plugin webpack incompatible con Turbopack — next dev muestra errores en una configuración personalizada webpack(). Turbopack ignora los plugins de webpack; migra o condiciona su uso.
• Conflicto de versión de @types/react — Discrepancia de peer-dependency entre librerías de componentes antiguas y los tipos de React 19. Fija @types/react a 19 y sobrescribe si es necesario.
• useFormState eliminado — Reemplazado por useActionState de react. El codemod suele detectarlo, pero confírmalo.

7. Prompt de corrección

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. Descripción del PR

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