Prompt to Migrate a Next.js 14 App to Next.js 16

Structured AI agent prompt to migrate a Next.js 14 App Router project to Next.js 16 with breaking-change handling and incremental steps.

Use this prompt to drive a careful, incremental Next.js 14 to 16 migration — handling the async params/searchParams API change, the React 19 peer dep, and deprecated next/headers patterns before upgrading.

Main Prompt

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.

Implementation Notes

In Next.js 15+, params and searchParams are Promise-wrapped. Accessing them synchronously will compile but throw at runtime — the audit in Step 1 is essential before upgrading.
cookies() and headers() are async in Next.js 15+; the most common failure mode is calling them inside a function that is not marked async.
React 19 removes some legacy APIs (defaultProps on function components, string refs). Run bun run typecheck between each step to surface these early.

Expected File Changes

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)

Acceptance Criteria

bun run typecheck exits 0 after all steps.
bun run build exits 0 with no warnings about deprecated APIs.
All dynamic routes render correctly in bun run dev.
No params or searchParams prop is accessed synchronously.

Test Commands

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"

Common AI Mistakes

Skipping the audit step and making all changes in one pass, causing hard-to-trace errors.
Typing async params as { params: { slug: string } } instead of { params: Promise<{ slug: string }> }.
Forgetting to upgrade @types/react alongside react, leaving type mismatches.
Not awaiting cookies() inside a nested helper function that itself is not async.

Fix Prompt

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.