Prompt-to-PR: Migrar Next.js 14 para 16

SOP passo a passo para migrar um projeto Next.js 14 App Router para Next.js 16 — Turbopack, React 19, APIs assíncronas e mudanças de cache abordados.

O Next.js 16 inclui React 19, params e searchParams assíncronos, cache de fetch reformulado e Turbopack como bundler de desenvolvimento padrão. Este guia mantém o agente focado nas mudanças significativas e evita que ele reescreva código funcional.

1. Requisito

Atualize next de 14.x para 16.x (e react/react-dom para 19.x) sem regressões de funcionalidade. Resolva todas as mudanças significativas reveladas pelo codemod oficial e quaisquer problemas residuais não detectados por ele.

2. Primeiro 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. Mudanças Esperadas nos Arquivos

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

package.json fixa next em ^16.0.0 e React em ^19.0.0.
Toda página/layout que desestrutura params agora usa await primeiro.
Nenhuma chamada síncrona cookies() ou headers() permanece em Server Components.
Chamadas fetch que antes dependiam de cache implícito agora têm uma opção explícita revalidate ou no-store.
next.config.ts não possui chaves obsoletas experimental.appDir ou swcMinify.
TypeScript compila com bun tsc --noEmit — zero erros.
O agente não reescreveu nenhum componente de UI ou lógica de negócio.

5. Comandos de Teste

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

params.id usado antes do await — Erro TypeScript: Property 'id' does not exist on type 'Promise<...>'. O agente às vezes usa await em params em um arquivo e não em outro.
cookies() sem await — erro em tempo de execução: cookies() was called outside of a Server Component. Adicione await.
Plugin webpack incompatível com Turbopack — next dev gera erro em uma configuração webpack() personalizada. Turbopack ignora plugins webpack; migre ou ative condicionalmente.
Conflito de versão do @types/react — incompatibilidade de dependência peer entre bibliotecas de componentes antigas e tipos do React 19. Fixe @types/react na versão 19 e substitua se necessário.
useFormState removido — substituído por useActionState do react. O codemod geralmente capta isso, mas confirme.

7. Prompt de Correção

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. Descrição do 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.