Prompt para migrar um aplicativo Next.js 14 para Next.js 16

Prompt estruturado de agente de IA para migrar um projeto Next.js 14 App Router para Next.js 16 com tratamento de mudanças de quebra e etapas incrementais.

Use este prompt para conduzir uma migração cuidadosa e incremental do Next.js 14 para o 16 — lidando com a mudança de API assíncrona de params/searchParams, a dependência React 19 e padrões obsoletos de next/headers antes da atualização.

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 Implementação

No Next.js 15+, params e searchParams são encapsulados em Promise. Acessá-los de forma síncrona irá compilar, mas lançará em tempo de execução — a auditoria no Passo 1 é essencial antes de atualizar.
cookies() e headers() são assíncronos no Next.js 15+; o modo de falha mais comum é chamá-los dentro de uma função que não está marcada como async.
O React 19 remove algumas APIs legadas (defaultProps em componentes de função, string refs). Execute bun run typecheck entre cada etapa para detectar essas cedo.

Mudanças Esperadas nos Arquivos

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)

Critérios de Aceitação

bun run typecheck retorna 0 após todas as etapas.
bun run build retorna 0 sem avisos sobre APIs obsoletas.
Todas as rotas dinâmicas renderizam corretamente em bun run dev.
Nenhum prop params ou searchParams é acessado de forma síncrona.

Comandos de Teste

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"

Erros Comuns de IA

Pular a etapa de auditoria e fazer todas as alterações de uma só vez, causando erros difíceis de rastrear.
Tipar params assíncronos como { params: { slug: string } } em vez de { params: Promise<{ slug: string }> }.
Esquecer de atualizar @types/react junto com react, deixando incompatibilidades de tipo.
Não aguardar cookies() dentro de uma função auxiliar aninhada que não é assíncrona.

Prompt de Correção

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.