adoption-composants-cache-nextjs
Activez les Composants Cache sur une application et amenez-la à une build réussie. Cette compétence séquence le travail ; les recettes par erreur se trouvent dans les fiches de correction de la superposition de développement et dans la sortie du terminal de build. Le guide de migration vers les Composants Cache est la référence canonique pour les concepts et les recettes par API que cette compétence applique — consultez-le chaque fois que les étapes de la compétence font référence à un motif ("use cache", cacheLife, placement de <Suspense>, etc.) et que vous souhaitez une explication complète.
prérequis
-
Projet App Router. Les Composants Cache sont une fonctionnalité de l'App Router ;
cacheComponents: truene fait rien pour les routespages/. Si le projet a une arborescencepages/ousrc/pages/mais pas d'arborescenceapp/ousrc/app/, arrêtez-vous et informez l'utilisateur — la migration Pages → App est un projet en soi, pas une partie de cette compétence. Une application hybride (à la foispages/etapp/) est acceptable : le flag affecte les routesapp/; les routespages/ne sont pas affectées et n'ont pas besoin d'opt-out. -
Next.js 16.3 ou ultérieur. Cette version contient les éléments sur lesquels cette compétence s'appuie :
cacheComponentsde premier niveau,export const instant, les avertissements de validation de navigation instantanée dans la superposition de développement, et le codemodcache-components-instant-false. Sinext --versionindique une version inférieure à 16.3, effectuez d'abord la mise à niveau :npx @next/codemod@latest upgrade latestpour appliquer les codemods de version à version.- Lisez le guide de mise à niveau de version pertinent (par exemple, Version 16) pour ce que le codemod ne couvre pas.
-
Aucune clé de configuration incompatible.
cacheComponents: truegénère une erreur sur tout fichier qui exporte encoredynamic,revalidateoufetchCache. Traduisez, ne supprimez pas. Chaque export encode un comportement que la route doit continuer à avoir ; migrez chacun d'eux vers son équivalent Composants Cache via les sections par clé du guide de migration. Si une valeur ne peut pas encore être traduite proprement, laissez un commentaire// TODO: Adoption Composants Cache — restaurer revalidate = 3600pour que la boucle le reprenne. Le codemodcache-components-instant-falsene touche pas à ceux-ci. -
experimental.dynamicIOest fatal. Il a été renommé encacheComponentsde premier niveau et l'ancienne clé provoque désormais un abandon avant même qu'une build puisse s'exécuter — supprimez-la (ou remplacez-la parcacheComponents: true) d'abord.experimental.useCacheest toujours accepté comme alias obsolète ; redondant une foiscacheComponents: truedéfini, supprimez-le donc par souci de clarté.
notes
-
Pas de baseline réussie avant le flag. Si l'application utilise déjà
"use cache", la build avant le flag échoue avec l'erreurveuillez activer le flag de fonctionnalité cacheComponents. L'activation du flag est la première chose que vous faites (dans l'approche Incrémentale, avant le codemod ; dans l'approche Directe, avant de corriger les routes) — pas une chose à faire après avoir obtenu une build réussie. Notez cela dans votre résumé de départ pour que cela ne ressemble pas à une régression. -
Documentation hors ligne. Les copies hors ligne des liens du guide se trouvent sous
node_modules/next/dist/docs/, avec la structure de répertoires numérotée pour l'ordre (par exemple,node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md). Le nom de fichier final correspond au slug. Si vous ne pouvez pas prédire le préfixe numéroté,find node_modules/next/dist/docs -name '<slug>.md'le résout. Les pages d'erreur/docs/messages/*ne sont pas regroupées. Si la documentation hors ligne est complètement absente, exécuteznpx @next/codemod@latest agents-mdpour écrire un index correspondant à la version dansAGENTS.md/CLAUDE.md.
la forme du travail
Il y a une boucle : parcourez l'arborescence des routes de haut en bas, une fonctionnalité à la fois, en adoptant chaque route avec next dev + un navigateur. La build est une vérification finale pour chaque fonctionnalité, pas la surface de travail.
Le choix à l'étape 1 est de savoir s'il faut d'abord faire taire les erreurs de validation ou les corriger au fur et à mesure. Dans les deux cas, la boucle est la même :
- Avec une pré-étape silencieuse (Incrémentale). Exécutez le codemod pour exclure chaque page et mise en page de la validation. Une fois que vous avez également corrigé ce que le codemod ne peut pas (appels E/S synchrones, exports
revalidate/dynamic/fetchCacherestants), la build réussit ; vous la livrez comme sa propre PR, puis commencez la boucle — en supprimant un opt-out à la fois et en adoptant cette route. Décompose le travail en petites PR révisables. - Sans (Directe). Activez
cacheComponentset commencez la boucle sur ce que la build signale en premier. Même boucle, mais chaque correction se trouve sur une seule branche jusqu'à ce que l'adoption soit terminée.
Dans les deux cas, le baromètre de succès par route est le même : la boucle de développement ne signale aucune erreur ET next build réussit. Vérifiez auprès de l'utilisateur après chaque fonctionnalité. Attendez-vous à passer la plupart du temps dans la boucle, pas dans la pré-étape.
contexte
cacheComponents: true exige que chaque route soit pré-rendable. Une route qui lit des données au moment de la requête en dehors de <Suspense> est "bloquante" et fait échouer la build. export const instant = false marque une route comme autorisée à bloquer, ce qui la débloque à la fois en développement et en build ; sur une mise en page, cela couvre tout le sous-arbre en dessous. Les lectures enveloppées dans une fonction "use cache" comptent comme des limites de cache, pas comme des lectures bloquantes.
Trois classes de bloqueurs affectent les agents dans cet ordre :
- Lectures au moment de la requête (
cookies(),headers(),await params,await searchParams). Les quatre bloquent lorsqu'ils sont attendus en haut d'une page ou d'une mise en page.paramsetsearchParamssont souvent oubliés car ils ne sont pas présentés comme des "données de requête" comme le sont les cookies et les en-têtes. La correction consiste à pousser la lecture dans un enfant enveloppé dans<Suspense>— et pourparams/searchParams, transmettez la promesse à l'enfant et attendez-la là ; n'utilisez pasawaiten haut de la page. - E/S synchrones au moment du module/rendu (
new Date(),Date.now(),Math.random(),crypto.randomUUID()). Ceux-ci font échouer la build même avecinstant = false— l'opt-out ne les supprime pas. S'ils se trouvent dans une mise en page partagée, ils bloquent chaque route en dessous. Le codemod ne peut pas les corriger ; vous devez traduire chacun d'eux (le mettre en cache avec"use cache"s'il est stable, ou l'envelopper dansawait connection()+<Suspense>s'il est par requête) avant que la build puisse réussir. Parcourez l'ensemble du dépôt à la recherche de ces appels avant d'exécuter quoi que ce soit d'autre. - Fichiers
"use cache"qui lisent des données de requête. Un fichier avec une directive"use cache"de premier niveau ne peut pas exporterinstant; combiner les deux génère une erreur avecSeules les fonctions asynchrones sont autorisées à être exportées dans un fichier "use cache".et signifie que la directive était erronée pour cette route. Supprimez-la avant d'exécuter le codemod.
surfaces de travail
trouver les routes bloquantes
Préférez next dev à next build pendant que vous travaillez.
next dev— la surface de travail. Visitez une route ; ses erreurs de blocage apparaissent dans la superposition de développement avec des traces de pile complètes et des fiches de correction liant la documentation par erreur. Travaillez une route à la fois — les erreurs ne s'accumulent pas à un seul endroit. La route elle-même renvoie toujours HTTP 200, alors lisez la superposition (ou.next-dev.log), pas les codes d'état. Une superposition effacée est une moitié de route propre — l'autre moitié est la vérification du navigateur (voir étape 2) et une build réussie pour cette route.next build— détection uniquement. La build est la vérification faisant autorité denext dev, pas son remplacement. Utilisez-la comme dernière barrière pour chaque fonctionnalité dans la boucle (une build réussie fait partie du baromètre de succès par route) et comme vérification finale sur l'ensemble de l'application. En Incrémentale, la build confirme également la pré-étape (le codemod a exclu toutes les routes, aucune mise en page partagée n'a encore de bloqueur E/S synchrone) avant de livrer cette PR. N'utilisez pas la build à la place de la boucle de développement pendant que vous travaillez sur une route — une erreur de compilation propre ne vous dit pas ce qui s'est retrouvé dans le shell statique par rapport à ce qui a été diffusé en continu. Par défaut, la build s'arrête à la première route bloquante, elle est donc également mauvaise pour dimensionner le travail. Deux flags aident lors de l'itération :--debug-build-pathsne build que les routes que vous nommez (modèles glob séparés par des virgules de chemins de fichiers relatifs à la racine du projet, par exemple--debug-build-paths="app/admin/**/page.tsx"— pas les chemins d'URL ;--debug-build-paths="app/(marketing)/about/page.tsx"— pas/about;--debug-build-paths="app/admin"ne correspond à rien et build silencieusement zéro routes), et--debug-prerenderdésactive la sortie anticipée afin que la build continue après le premier échec de pré-rendu, signale chaque route bloquante et imprime une trace de pile plus complète qui nomme le fichier et la ligne d'origine.
Chaque erreur de blocage a une page de documentation — ouvrez-la. La superposition de développement et le terminal de build impriment un lien https://nextjs.org/docs/messages/<slug> avec chaque erreur. Cette page est la recette canonique pour la correction ; le message en ligne est un résumé. Récupérez le lien pour chaque erreur distincte que vous rencontrez, même si vous pensez connaître le motif — les recettes évoluent, et la même classe d'erreur peut avoir des corrections correctes différentes selon ce que la route lit. N'improvisez pas à partir du seul message en ligne. (Les pages /docs/messages/* ne sont pas regroupées hors ligne ; si vous n'avez pas de réseau, repliez-vous sur les guides par API sous node_modules/next/dist/docs/ et notez la limitation lorsque vous faites votre rapport.)
vérifier chaque correction à l'exécution
Une build réussie ou une superposition effacée ne prouve pas que la route se comporte réellement — les Composants Cache sont une préoccupation d'exécution (un shell statique avec des données diffusées en continu). Vérifiez après chaque correction, pas seulement à la fin.
Par ordre de préférence :
-
next-dev-loop— fortement recommandé. Effectue des vérifications croisées de/_next/mcpavec le navigateur en direct viaagent-browseret révèle les problèmes de compilation et d'exécution en un seul passage. Les diagnostics (arbre React, limites de suspense, console + réseau) sont plus riches que de tâtonner avecnext devmanuellement.Installez-le avant de commencer la boucle. N'attendez pas de rencontrer quelque chose que
next devseul ne peut pas expliquer. Exécutez :npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loopLa compétence nécessite
agent-browser >= 0.27.0et vous guidera tout au long.Nécessite Turbopack. Si le script
devdepackage.jsontransmet--webpack, signalez-le à l'utilisateur et demandez s'il y a une raison de rester sur webpack. Sinon, passez à Turbopack (le défaut de Next.js 16.3+). S'ils souhaitent conserver webpack, ignorez cette installation et utilisez la boucle de build uniquement à la place.Vous n'avez pas besoin d'autorisation pour installer
next-dev-looplui-même. C'est un outil, comme l'installation d'une dépendance de développement. Si un utilisateur est en ligne, dites-lui brièvement que vous l'installez pour vérification. Dans une exécution non interactive (CI, tableau de bord, sandbox), installez-le sans demander — "impossible d'inviter l'utilisateur" n'est pas une raison pour sauter. Le seul saut légitime est un véritable blocage technique : pas de réseau, pas de npm, système de fichiers en lecture seule, une politique de non-nouvelles-dépendances déclarée, ou un script de développement webpack uniquement. Si vous sautez, nommez le bloqueur spécifique dans votre rapport final. -
Un navigateur que vous pouvez piloter vous-même. Playwright,
agent-browserdirectement, n'importe quel outil d'automatisation de navigateur. Utilisez-le uniquement lorsquenext-dev-loopest véritablement bloqué. Vous manquerez les vérifications côté framework (/_next/mcp), donc les assertions DOM seules n'attrapent pas toutes les régressions — soyez plus prudent sur ce que vous appelez "vérifié". -
Build uniquement. Si vous ne pouvez pas du tout exécuter de serveur de développement, la build est votre seul signal. Les routes
○ (Statique)sans<Suspense>sont entièrement vérifiées par la build (rien de diffusé en continu à tester). Les routes◐ (Pré-rendu Partiel)ne sont vérifiées que pour le shell — signalez-les lorsque vous faites votre rapport. -
Aucun outillage du tout. Demandez à l'utilisateur d'exécuter le serveur de développement (ou la build) et de rapporter ce qu'il voit, ou validez le jalon que vous avez atteint et passez le relais.
étape 1 : choisir une stratégie
Demandez à l'utilisateur. Formulez-la comme une question sur la forme des PR, pas comme un appel à dimensionnement. N'utilisez jamais les libellés internes (Incrémentale, Directe, jalon A) lorsque vous parlez à l'utilisateur — ce sont votre propre échafaudage. Demandez en termes de PR et de fonctionnalités, par exemple : "Souhaitez-vous que j'ouvre d'abord une PR qui active les Composants Cache et exclut toutes les routes de la validation, puis que je gère les adoptions de routes réelles fonctionnalité par fonctionnalité dans des PR de suivi ? Ou que je fasse tout sur une seule branche ?" Même sur une toute petite application, le chemin incrémental a encore de la valeur (taille de PR révisable, réversible, les marqueurs // TODO: Adoption Composants Cache servent également de file d'attente de travail pour la session suivante). Ne choisissez pas à leur place.
S'il n'y a pas d'utilisateur à qui demander, par défaut choisissez Incrémentale et documentez le choix.
- Incrémentale — pré-étape silencieuse + la boucle. Exécutez le codemod pour exclure chaque page et mise en page de la validation, faites réussir la build, arrêtez-vous et vérifiez auprès de l'utilisateur (voir fin de la pré-étape), puis entrez dans la boucle de l'étape 2 et livrez chaque fonctionnalité comme une PR de suivi.
- Directe — sautez la pré-étape. Activez
cacheComponentset allez directement à la boucle de l'étape 2 ; les routes bloquantes de la build sont la file d'attente de travail.
incrémentale
Avant d'invoquer le codemod, corrigez les deux classes de bloqueurs qu'il ne peut pas traiter.
-
E/S synchrones au moment du module/rendu. Parcourez l'ensemble du dépôt à la recherche de
new Date(),Date.now(),Math.random(), etcrypto.randomUUID()(pas seulementapp/**/layout.{js,jsx,ts,tsx}— la lecture pourrait se trouver dans n'importe quel composant importé par une mise en page). Traduisez chaque correspondance en utilisant la recette de sa carte d'erreurblocking-prerender-*. -
Configurations de segment incompatibles. Recherchez
^export const (revalidate|dynamic|fetchCache)dansapp/et traduisez selon la note deprérequisci-dessus. Le codemod n'y touche pas ; les laisser en place fait échouer la build après le codemod.
Le codemod refuse de s'exécuter sur un arbre de travail sale. Validez ou mettez de côté le travail non lié d'abord, ou passez --force pour permettre à ses modifications d'atterrir à côté de votre travail en cours. Faux positif courant : si vous avez récemment mis à niveau Next.js, package.json et le fichier de verrouillage seront déjà sales — validez-les d'abord.
Utilisez le canal @canary
…
[tronqué pour la traduction]