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 parsuspended_by[].name, supprimer les hooks SSR-only.
Choisissez-en une et exécutez-la de bout en bout.
prérequis
next-dev-loopinitié pour cette session — il ouvre le navigateur piloté, expose la CLIagent-browser, et branche le serveur MCP de développement qui fournitmcp get_logs.cacheComponents: truedansnext.config.ts. Refuser sinon.
pré-vérification (partagée)
- Confirmer
cacheComponents: true. - 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.) agent-browser get urlpour 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.lengthjusqu'à 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 sousverifyest 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.