Communitygithub.com

0n6k4v-Coder/skills

Activez les Composants Cache dans une application Next.js et résolvez les routes bloquantes qu'elle révèle. Utilisez cette compétence lorsque l'utilisateur souhaite activer, adopter ou migrer vers les Composants Cache, basculer le flag `cacheComponents`, résoudre un flot d'erreurs de pré-rendu bloquant / de validation instantanée, exécuter le codemod `cache-components-instant-false`, ou décider d'exclure des routes avec `export const instant = false` ou de les corriger sur place.

Qu'est-ce que skills ?

Cette compétence guide l'adoption des Composants Cache dans une application Next.js, en séquençant le travail depuis l'activation du flag `cacheComponents: true` jusqu'à l'obtention d'une build réussie. Elle est conçue pour les applications utilisant l'App Router de Next.js et nécessite la version 16.3 ou ultérieure. La compétence offre deux stratégies : une approche incrémentale qui opte d'abord toutes les routes hors de la validation via un codemod, puis les adopte une par une dans des PR séparées, et une approche directe qui active le flag et corrige les routes bloquantes au fur et à mesure. Elle fonctionne en boucle sur l'arborescence des routes, en s'appuyant sur `next dev` pour détecter les erreurs de blocage (lectures de données au moment de la requête, E/S synchrones, fichiers `"use cache"` lisant des données de requête) et sur `next build` comme vérification finale. La compétence recommande fortement l'utilisation de `next-dev-loop` pour une vérification runtime plus riche et préconise de consulter la documentation officielle pour chaque erreur rencontrée.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-cache-components-adoption

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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: true ne fait rien pour les routes pages/. Si le projet a une arborescence pages/ ou src/pages/ mais pas d'arborescence app/ ou src/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 fois pages/ et app/) est acceptable : le flag affecte les routes app/ ; les routes pages/ 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 : cacheComponents de premier niveau, export const instant, les avertissements de validation de navigation instantanée dans la superposition de développement, et le codemod cache-components-instant-false. Si next --version indique une version inférieure à 16.3, effectuez d'abord la mise à niveau :

  • Aucune clé de configuration incompatible. cacheComponents: true génère une erreur sur tout fichier qui exporte encore dynamic, revalidate ou fetchCache. 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 = 3600 pour que la boucle le reprenne. Le codemod cache-components-instant-false ne touche pas à ceux-ci.

  • experimental.dynamicIO est fatal. Il a été renommé en cacheComponents de 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 par cacheComponents: true) d'abord. experimental.useCache est toujours accepté comme alias obsolète ; redondant une fois cacheComponents: true dé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'erreur veuillez 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écutez npx @next/codemod@latest agents-md pour écrire un index correspondant à la version dans AGENTS.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/fetchCache restants), 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 cacheComponents et 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 :

  1. 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. params et searchParams sont 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 pour params/searchParams, transmettez la promesse à l'enfant et attendez-la là ; n'utilisez pas await en haut de la page.
  2. E/S synchrones au moment du module/rendu (new Date(), Date.now(), Math.random(), crypto.randomUUID()). Ceux-ci font échouer la build même avec instant = 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 dans await 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.
  3. Fichiers "use cache" qui lisent des données de requête. Un fichier avec une directive "use cache" de premier niveau ne peut pas exporter instant ; combiner les deux génère une erreur avec Seules 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é de next 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-paths ne 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-prerender dé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 :

  1. next-dev-loop — fortement recommandé. Effectue des vérifications croisées de /_next/mcp avec le navigateur en direct via agent-browser et 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 avec next dev manuellement.

    Installez-le avant de commencer la boucle. N'attendez pas de rencontrer quelque chose que next dev seul ne peut pas expliquer. Exécutez :

    npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop
    

    La compétence nécessite agent-browser >= 0.27.0 et vous guidera tout au long.

    Nécessite Turbopack. Si le script dev de package.json transmet --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-loop lui-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.

  2. Un navigateur que vous pouvez piloter vous-même. Playwright, agent-browser directement, n'importe quel outil d'automatisation de navigateur. Utilisez-le uniquement lorsque next-dev-loop est 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é".

  3. 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.

  4. 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 cacheComponents et 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.

  1. E/S synchrones au moment du module/rendu. Parcourez l'ensemble du dépôt à la recherche de new Date(), Date.now(), Math.random(), et crypto.randomUUID() (pas seulement app/**/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'erreur blocking-prerender-*.

  2. Configurations de segment incompatibles. Recherchez ^export const (revalidate|dynamic|fetchCache) dans app/ et traduisez selon la note de prérequis ci-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]

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Skills associés