Invite pour migrer une application Next.js 14 vers Next.js 16

Invite structurée pour agent IA afin de migrer un projet Next.js 14 App Router vers Next.js 16 avec gestion des changements cassants et étapes incrémentales.

Utilisez cette invite pour mener une migration prudente et incrémentale de Next.js 14 vers 16 — en gérant le changement d’API asynchrone params/searchParams, la dépendance de paire React 19, et les motifs obsolètes de next/headers avant la mise à niveau.

Invite principale

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.

Notes d’implémentation

Dans Next.js 15+, params et searchParams sont enveloppés dans une Promise. Y accéder de manière synchrone compilera mais générera une erreur à l’exécution — l’audit à l’étape 1 est essentiel avant la mise à niveau.
cookies() et headers() sont asynchrones dans Next.js 15+ ; le mode d’échec le plus courant est de les appeler à l’intérieur d’une fonction qui n’est pas marquée async.
React 19 supprime certaines API héritées (defaultProps sur les composants fonction, les refs sous forme de chaîne). Exécutez bun run typecheck entre chaque étape pour les détecter tôt.

Modifications de fichiers attendues

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ères d’acceptation

bun run typecheck se termine avec le code 0 après toutes les étapes.
bun run build se termine avec le code 0 sans avertissements concernant les API obsolètes.
Toutes les routes dynamiques s’affichent correctement dans bun run dev.
Aucune propriété params ou searchParams n’est accédée de manière synchrone.

Commandes de test

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"

Erreurs courantes de l’IA

Ignorer l’étape d’audit et effectuer toutes les modifications en une seule passe, provoquant des erreurs difficiles à tracer.
Typer les paramètres asynchrones comme { params: { slug: string } } au lieu de { params: Promise<{ slug: string }> }.
Oublier de mettre à niveau @types/react en même temps que react, laissant des incompatibilités de types.
Ne pas faire un await sur cookies() dans une fonction d’aide imbriquée qui elle-même n’est pas asynchrone.

Invite de correction

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.