Communitygithub.com

Optimiseur de composants cache Next.js

Optimise une application Next.js avec `cacheComponents: true` — soit la coque statique au premier affichage, soit la navigation entre les routes. Choisit la boucle de diagnostic correspondante et l'exécute.

Qu'est-ce que Optimiseur de composants cache Next.js ?

Cette compétence est conçue pour les développeurs utilisant Next.js avec `cacheComponents: true` dans le but d'optimiser les performances de rendu. Elle offre deux boucles de travail principales : la boucle 'Page-render' pour améliorer la coque statique d'une page unique, et la boucle 'Nav' pour accélérer la navigation entre deux routes en affichant immédiatement le squelette statique de la page de destination. La compétence diagnostique automatiquement le problème, puis applique des leviers de refactorisation partagés comme le 'Push-down' (extraire les opérations I/O dans des composants Suspense) et la mise en cache (`use cache`). Elle exige un environnement de diagnostic `next-dev-loop` déjà actif et refuse de fonctionner si `cacheComponents` n'est pas activé. Chaque modification passe par un 'plan mode' pour une validation humaine avant application, et la vérification se fait par comparaison de captures d'écran avant/après pour garantir une différence visible. La compétence détaille aussi les anti-patrons à éviter (comme remplacer les limites Suspense granulaires par un squelette de chargement global) et les pièges courants (instabilité des diagnostics, comportement du dev vs production).

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

Demander à votre IA préférée

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

Documentation

next-cache-components-optimizer

Deux boucles, leviers et primitives partagés, diagnostics différents :

  • Boucle Page-render (ppr-loop.md) — agrandir la coque statique d'une seule page. Classer les zones de fallback Suspense lors d'un rendu de la coque uniquement.
  • Boucle Nav (instant-nav-loop.md) — lorsque l'utilisateur clique sur un lien de A à B, afficher immédiatement la mise en page statique de B (chrome, structure, fallbacks en forme de contenu) au lieu de conserver l'interface de A jusqu'à ce que les données de B soient résolues. Capturer les limites suspendues de B après le pushstate, les classer par suspended_by[].name, supprimer les hooks SSR-only.

Choisissez-en une et exécutez-la de bout en bout.

prérequis

  • next-dev-loop initié pour cette session — il ouvre le navigateur piloté, expose la CLI agent-browser, et branche le serveur MCP de développement qui fournit mcp get_logs.
  • cacheComponents: true dans next.config.ts. Refuser sinon.

pré-vérification (partagée)

  1. Confirmer cacheComponents: true.
  2. L'utilisateur doit déjà se trouver sur la page nécessaire à chaque boucle dans le navigateur piloté (depuis next-dev-loop) — connecté, avec tout état configuré. Cette compétence ne peut pas gérer l'authentification, le SSO ou le MFA ; elle prend la configuration manuelle comme point de départ. (Chaque sous-boucle indique quelle page elle attend.)
  3. agent-browser get url pour ancrer la route actuelle.

Chaque boucle définit le cookie instantané selon les besoins (voir la section cookie instantané partagée ci-dessous).

cookie instantané (partagé)

Les deux boucles utilisent le cookie next-instant-navigation-testing pour geler les écritures dynamiques de données du framework. Une fois défini, le contenu visible sur la page est la coque statique + les fallbacks Suspense — c'est ce que nous capturons pour évaluer l'optimisation.

Définissez-le avec un tuple à verrouillage en attente [0, "<id-unique>"]. L'id est une chaîne unique ; la convention est un tampon aléatoire préfixé par p pour que les portées concurrentes n'entrent pas en collision :

agent-browser cookies set next-instant-navigation-testing '[0,"p<aléatoire>"]' \
  --url <origine>

La pré-vérification de chaque boucle spécifie quand le définir dans le flux. Supprimez-le à la fin (voir nettoyage ci-dessous).

décider quelle boucle

  • Page-render lorsque le problème concerne le chargement initial d'une route. Lire ppr-loop.md.
  • Nav lorsqu'il s'agit de naviguer entre deux routes. Lire instant-nav-loop.md.

Ambigu → demander.

leviers de refactorisation partagés

  • Push-down — extraire les opérations I/O dans un enfant encapsulé dans Suspense afin que le parent reste statique et que les frères statiques remontent dans la coque.
    • Récursif, pas d'encapsulation aveugle. Si une limite Suspense encapsule déjà un composant contenant à la fois du contenu statique et des I/O, lire à l'intérieur, extraire le JSX dépendant des I/O dans une nouvelle feuille, et faire remonter les frères statiques.
  • Cache — 'use cache' + cacheLife(<profil>). Toujours demander la fraîcheur à l'utilisateur ; mapper à un préréglage (seconds / minutes / hours / days / weeks / max / default).

Le push-down et le cache se composent : le push-down soulève la structure statique, le cache élimine l'écart de données restant.

proposer via le mode plan (partagé)

Chaque refactorisation passe par le mode plan avant d'être appliquée. Considérez cela comme un signal : le travail d'application est une ingénierie agentique non triviale, pas une modification basée sur un modèle. Cette compétence fournit le cadre — quel levier utiliser, quel candidat corriger, quel delta visible est attendu — mais le vrai travail (quel fichier modifier, comment extraire proprement les I/O, où placer la nouvelle limite Suspense, quel profil cacheLife demander à l'utilisateur) est un jugement que vous devez réfléchir. Le mode plan force une proposition cohérente avant de toucher au code, et donne à l'utilisateur une chance de rediriger sur l'une de ces décisions.

abandon sans coque (partagé)

Les leviers présupposent qu'il existe une coque à agrandir ou à mettre en cache. Si la route est entièrement bloquante — HTTP 500 avec blocking-route ou NEXT_STATIC_GEN_BAILOUT dans mcp get_logs, ou zéro limites Suspense sur une page rendue visiblement — il n'y a pas de coque. Signaler le bloqueur structurel et s'arrêter ; l'utilisateur doit encapsuler l'accès dynamique problématique dans <Suspense> avant que l'une ou l'autre boucle puisse aider.

la vérification nécessite un delta visible (partagé)

Chaque boucle capture une capture d'écran de base de la coque avant d'appliquer toute modification, puis une nouvelle capture après. Signaler les deux chemins dans le résumé final pour que l'utilisateur puisse voir ce qui a changé. Les deux captures doivent différer visiblement — zone de fallback réduite, contenu promu à la surface statique, fallback cible disparu ou en forme de contenu. Des captures identiques signifient que la refactorisation n'a pas fonctionné ; annuler. "Compiler proprement" n'est pas le critère.

Masquer la superposition de développement avant chaque capture d'écran. La superposition de développement Next.js (<nextjs-portal> à la racine du document) affiche des conseils de navigation instantanée, des erreurs de build et autres chrome de développement qui polluent la comparaison avant/après. La masquer, capturer, restaurer :

agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <chemin>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"

anti-patrons (partagé)

Ne remplacez pas les limites Suspense granulaires par un squelette de chargement global. Un loading.tsx pour tout le segment, ou un <Suspense fallback={<Skeleton />}> au niveau racine (ou pire, fallback={null} qui vide l'interface), va à l'encontre de l'optimisation de cette compétence — qui consiste à extraire un vrai chrome statique au-dessus de chaque limite granulaire et à utiliser des fallbacks en forme de contenu par région. Un substitut grossier "la page charge" contourne entièrement le travail.

pièges (partagé)

  • Le développement ne pré-extrait pas comme la production, et les routes compilent au premier accès — donc après une navigation ou un rechargement, le DOM continue de se mettre à jour notablement plus longtemps que l'expérience de production finale. Attendez patiemment que le DOM se stabilise avant de capturer l'arbre React ou de prendre une capture d'écran — par exemple, interrogez document.documentElement.innerHTML.length jusqu'à ce qu'il reste inchangé sur deux lectures consécutives. Un délai court fixe risque d'échantillonner en plein rendu.
  • N'essayez pas de vérifier le pré-extraction de navigation en inspectant le trafic réseau de développement — le développement ne déclenche pas du tout de requêtes de pré-extraction, donc l'onglet réseau, les appels manuels à router.prefetch() et <Link prefetch={true}> sembleront tous défectueux, que votre code soit correct ou non. La recette de navigation SPA avec cookie verrouillé dans instant-nav-loop.md sous verify est déjà la recette canonique pour cela — elle simule ce que la production pré-rendrait dans le RSC pré-extrait sans nécessiter que la pré-extraction se déclenche réellement. Utilisez-la ; n'inventez pas d'alternative basée sur l'onglet réseau.
  • Le pipeline de diagnostic peut être instable — le timing de fixation des outils de développement, les courses de stabilisation du DOM et les effets de compilation du développement peuvent chacun produire des captures incohérentes d'une exécution à l'autre. Lorsqu'un résultat semble étrange (un candidat apparaît que vous n'attendez pas, ou un que vous attendez n'apparaît pas), réexécutez le diagnostic 2 à 3 fois et recoupez ; les limites qui apparaissent systématiquement sont réelles, les apparitions uniques sont du bruit.

référence (primitives partagées)

agent-browser react suspense          ajouter --only-dynamic pour filtrer
--json                                les limites effectivement mises en
                                      suspens côté serveur. Chaque entrée
                                      a jsx_source + suspended_by[] avec
                                      les noms bruts des bloqueurs
                                      (usePathname, cookies, fetch,
                                      cache, ...) ; classer par
                                      nom pour les règles de chaque boucle

POST /__nextjs_original-stack-frames  body { frames: StackFrame[],
                                      isServer, isEdgeServer,
                                      isAppDirectory } ; renvoie un
                                      résultat par trame avec
                                      fichier:ligne:colonne

mcp get_logs                          outil MCP de développement depuis
                                      next-dev-loop ; signale les 500
                                      blocking-route /
                                      NEXT_STATIC_GEN_BAILOUT

cacheLife('<profil>')                 default | seconds | minutes
                                      | hours | days | weeks | max

Primitives par boucle dans instant-nav-loop.md.

nettoyage (partagé)

Supprimer le cookie par son nom — le remplacer par un timbre expiré :

agent-browser cookies set next-instant-navigation-testing x \
  --url <origine> --expires 1

Ne jamais utiliser agent-browser cookies clear (sans arguments) — cela supprime l'authentification.


Compagnon de next-dev-loop — initiez d'abord celui-ci.

Individual skills in this repo

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

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Verify Next.js runtime behavior after editing app code. Use this skill to confirm a change actually works in a running app — not just that it compiles or type-checks. Combines /_next/mcp (Next.js's view) with agent-browser (the browser's view). Requires a running `next dev`.

Skills associés