Next.js 16 : planifier, coder et déboguer avec un agent

Déclencheurs

nextjs
next.js
next
app router
server component
ssr
ssg
vercel
next 16
pages router
middleware
next api

Liens

Docs: https://nextjs.org/docs
Guide de mise à jour (v16): https://nextjs.org/docs/app/guides/upgrading/version-16
Notes de version/blog: https://nextjs.org/blog/next-16

Mise à jour

# Mise à jour automatisée
npx @next/codemod@canary upgrade latest

# Mise à jour manuelle
npm install next@latest react@latest react-dom@latest

# Nouveau projet
npx create-next-app@latest

Codemod couvre (haut niveau) : déplace la config Turbopack, migre next lint → ESLint CLI, migre middleware → proxy, supprime certains préfixes unstable_, supprime experimental_ppr au niveau des routes.

TypeScript : mettez aussi à jour @types/react et @types/react-dom.

Quoi de neuf (v16)

Cache Components : mise en cache opt-in via la directive "use cache" ; évolue/absorbe PPR.
Next.js DevTools MCP : intégration du Model Context Protocol pour le débogage assisté par IA.
proxy.ts : délimitation plus claire des frontières réseau ; middleware.ts déprécié pour la plupart des cas.
Meilleurs logs/métriques : sortie de timing plus détaillée pour next dev et la build.

Performance / DX

Turbopack : stable ; bundler par défaut (opt out avec next dev --webpack, next build --webpack).
Si vous avez une config webpack personnalisée, next build peut échouer (pour éviter les malconfigurations). Corrigez-le en migrant la config, en utilisant next build --webpack, ou en utilisant Turbopack et en supprimant/ignorant la config webpack.
Config Turbopack déplacée : experimental.turbopack → turbopack au niveau supérieur dans next.config.*.
Pièges de migration Turbopack :
- Imports Sass : supprimez le préfixe ~ spécifique à Webpack (ex. @import 'bootstrap/...';).
- Les bundles navigateur ne doivent pas importer les built-ins Node (ex. fs). Si inévitable, utilisez turbopack.resolveAlias en solution temporaire.
Cache système de fichiers Turbopack (dev, bêta) : experimental.turbopackFileSystemCacheForDev: true.
Support React Compiler : stable via opt-in reactCompiler: true (attendez-vous à un coût de build/compilation plus élevé).
API Build Adapters : alpha (adaptateurs de build personnalisés).
Réécriture du routage/prefetching : déduplication de layout + prefetching incrémental.

APIs de caching (signatures clés)

revalidateTag(tag, profile) requiert maintenant un profil cacheLife (ou { expire }) pour le comportement SWR.
updateTag(tag) (Server Actions uniquement) : sémantique de lecture après écriture.
refresh() (Server Actions uniquement) : actualise les données non cachées ; ne modifie pas le cache.
cacheLife et cacheTag sont stables (pas de préfixe unstable_).

Prérequis (v16)

Node.js : 20.9+ (Node 18 non supporté)
TypeScript : 5.1+
Navigateurs : Chrome/Edge/Firefox 111+, Safari 16.4+

Breaking / Changements de comportement (impact élevé)

APIs Request asynchrones : accès sync supprimé. Utilisez await params, await searchParams, await cookies(), await headers(), await draftMode().
Conseil (TypeScript) : npx next typegen peut générer des helpers comme PageProps, LayoutProps, RouteContext pour migrer les types params/searchParams en toute sécurité.
Images de métadonnées : opengraph-image, twitter-image, icon, apple-icon reçoivent maintenant params (et id) comme Promises dans la fonction image.
Sitemaps : sitemap({ id }) reçoit maintenant id comme Promise lors de l'utilisation de generateSitemaps.
Routes parallèles : les slots nécessitent un default.js explicite.
Changements de défauts next/image (TTL du cache, sizes/qualities) ; src local avec query strings nécessite images.localPatterns.

Autres changements de comportement notables :

next dev et next build utilisent des répertoires de sortie séparés (next dev → .next/dev) et un fichier verrou empêche les instances concurrentes.
Comportement du scroll : Next.js ne remplace plus le scroll-behavior: smooth global lors des navigations ; ajoutez data-scroll-behavior="smooth" sur <html> pour restaurer le comportement de remplacement précédent.
ESLint : @next/eslint-plugin-next utilise par défaut la Flat Config ; les projets hérités .eslintrc peuvent nécessiter une migration.

Supprimé / Déprécié (haut niveau)

Supprimé : support AMP ; next lint (utilisez ESLint/Biome directement) ; option eslint dans next.config.* ; serverRuntimeConfig/publicRuntimeConfig (utilisez les variables env) ; experimental.ppr + experimental_ppr au niveau des routes ; unstable_rootParams.
Déprécié : nom de fichier middleware.ts (préférez proxy.ts) ; next/legacy/image ; images.domains (préférez images.remotePatterns) ; forme mono-argument de revalidateTag(tag).
Note proxy.ts : proxy s'exécute sur nodejs uniquement ; le runtime Edge n'est pas supporté dans proxy. Gardez middleware.ts si vous devez rester sur Edge.
Exemple de renommage config : skipMiddlewareUrlNormalize → skipProxyUrlNormalize.

Vérifier

La version de Next.js ciblée est nommée explicitement (ex. 'Next 16') et le changement ne repose pas silencieusement sur des fonctionnalités d'une autre version majeure
next build (ou l'équivalent du projet) a été exécuté et complété sans erreur ; la sortie de build / table de routes est capturée
Les server components vs client components ont été choisis délibérément pour chaque nouveau fichier ; le choix est justifié dans un commentaire ou note PR
next dev a été chargé et les routes touchées se sont rendues sans avertissements console ou désaccords d'hydratation
Le comportement de caching/revalidation (options fetch, revalidate, dynamic) est défini explicitement sur les nouvelles récupérations de données, pas laissé aux défauts
La vérification de type et le linting (tsc --noEmit, next lint) réussissent sur les fichiers modifiés ; la sortie est dans la transcription

nextjs16-skills