# Prompt-to-PR: Migrer Next.js 14 vers 16

> Procédure pas à pas (SOP) pour migrer un projet Next.js 14 avec App Router vers Next.js 16 — Turbopack, React 19, les API asynchrones et les modifications de mise en cache sont couverts.

**Type:** Playbook  
**Tools:** Cursor, Claude Code, Codex, Windsurf  
**Stack:** Next.js, TypeScript  
**Difficulty:** hard  
**Updated:** 2026-06-08

---

Next.js 16 embarque React 19, les `params` et `searchParams` asynchrones, une refonte complète du cache des requêtes `fetch`, et Turbopack comme bundler de développement par défaut. Ce guide permet à l'agent de se concentrer sur les changements cassants et l'empêche de réécrire du code fonctionnel.

## 1. Prérequis

Mettre à jour `next` de 14.x à 16.x (et `react`/`react-dom` vers 19.x) sans aucune régression fonctionnelle. Traiter chaque changement cassant révélé par le codemod officiel ainsi que tout problème résiduel qu'il n'a pas détecté.

## 2. Premier Prompt

```txt title="First 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. Modifications de fichiers attendues

```txt
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. Liste de vérification

- `package.json` fixe `next` à `^16.0.0` et React à `^19.0.0`.
- Chaque page/layout qui déstructure `params` doit d'abord l'attendre avec `await`.
- Aucun appel synchrone à `cookies()` ou `headers()` ne subsiste dans les composants serveur.
- Les appels `fetch` qui reposaient auparavant sur une mise en cache implicite doivent avoir une option `revalidate` ou `no-store` explicite.
- `next.config.ts` ne contient pas les clés obsolètes `experimental.appDir` ou `swcMinify`.
- TypeScript compile avec `bun tsc --noEmit` — zéro erreur.
- L'agent n'a réécrit aucun composant d'interface ni logique métier.

## 5. Commandes de test

```bash
# 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. Échecs courants

- **`params.id` utilisé avant await** — Erreur TypeScript : `Property 'id' does not exist on type 'Promise<...>'`. L'agent attend parfois `params` dans un fichier mais pas dans un autre.
- **`cookies()` non attendu** — Erreur d'exécution : `cookies() was called outside of a Server Component`. Ajoutez `await`.
- **Plugin webpack incompatible avec Turbopack** — `next dev` génère une erreur sur une configuration `webpack()` personnalisée. Turbopack ignore les plugins webpack ; migrez-les ou conditionnez-les.
- **Conflit de version `@types/react`** — Incompatibilité de dépendance peer entre les anciennes bibliothèques de composants et les types React 19. Épinglez `@types/react` à la version 19 et remplacez si nécessaire.
- **`useFormState` supprimé** — remplacé par `useActionState` de `react`. Le codemod détecte généralement cela, mais vérifiez.

## 7. Prompt de correction

```txt title="Fix Prompt"
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. Description de la PR

```md title="PR description"
## 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.
```