¿Qué hace optimizador-cache-componentes-next?
Dos bucles, palancas y primitivas compartidas, diagnósticos diferentes:
- Bucle de renderizado de página (ppr-loop.md) — expande la cáscara estática de una sola página. Clasifica las áreas de reserva Suspense en un renderizado solo de cáscara.
- Bucle de navegación (instant-nav-loop.md) — cuando el usuario hace clic en un enlace de A a B, muestra el diseño estático de B inmediatamente (chrome, estructura, reservas con forma de contenido) en lugar de mantener la interfaz de usuario de A hasta que se resuelvan los datos de B. Captura los límites suspendidos de B después de
pushstate, clasifica cada uno porsuspended_by[].name, elimina hooks solo de SSR.
Elige uno y ejecútalo de principio a fin.
requiere
next-dev-loopiniciado para esta sesión — abre el navegador con cabeza, expone la CLIagent-browsery conecta el servidor MCP de desarrollo que proporcionamcp get_logs.cacheComponents: trueennext.config.ts. Recházalo si no.
prevuelo (compartido)
- Confirma
cacheComponents: true. - El usuario ya debe estar en la página que cada bucle necesita en el navegador con cabeza (de
next-dev-loop) — con sesión iniciada y cualquier estado configurado. Esta habilidad no puede manejar autenticación, SSO o MFA; toma la configuración manual como punto de partida. (Cada sub-bucle nombra qué página espera). agent-browser get urlpara anclar la ruta actual.
Cada bucle establece la cookie instantánea según sea necesario (consulta la sección cookie instantánea compartida a continuación).
cookie instantánea (compartida)
Ambos bucles usan la cookie next-instant-navigation-testing para congelar las escrituras dinámicas de datos del framework. Una vez establecida, el contenido visible en la página es la cáscara estática + las reservas Suspense — eso es lo que capturamos para evaluar la optimización.
Establécela con una tupla de bloqueo pendiente [0, "<id-único>"]. El id es cualquier cadena única; la convención es un sello aleatorio con prefijo p para que los ámbitos concurrentes no colisionen:
agent-browser cookies set next-instant-navigation-testing '[0,"p<aleatorio>"]' \
--url <origen>
El prevuelo de cada bucle especifica cuándo establecerla dentro del flujo. Límpiala al final (consulta limpieza a continuación).
decide qué bucle
- Renderizado de página cuando la queja es sobre la carga inicial de una ruta. Lee ppr-loop.md.
- Navegación cuando se trata de navegar entre dos rutas. Lee instant-nav-loop.md.
Ambiguo → pregunta.
palancas de refactorización compartidas
- Empujar hacia abajo — extraer E/S en un hijo envuelto en Suspense para que el padre permanezca estático y los hermanos estáticos se eleven a la cáscara.
- Recurrir, no envolver a ciegas. Si un límite Suspense ya envuelve un componente que contiene tanto contenido estático como la E/S, lee dentro, extrae el JSX dependiente de E/S en una nueva hoja y eleva los hermanos estáticos hacia arriba.
- Cachear —
'use cache'+cacheLife(<perfil>). Siempre pregunta al usuario por frescura; mapea a un preajuste (seconds/minutes/hours/days/weeks/max/default).
Empujar hacia abajo y cachear se componen: empujar hacia abajo eleva la estructura estática, cachear elimina la brecha de datos restante.
proponer mediante modo de planificación (compartido)
Cada refactorización pasa por el modo de planificación antes de aplicarse. Trata esto como una señal: el trabajo de aplicación es ingeniería agéntica no trivial, no una edición con plantilla. Esta habilidad proporciona el marco — qué palanca usar, qué candidato arreglar, cuál es el delta visible esperado — pero el trabajo real (qué archivo editar, cómo extraer limpiamente la E/S, dónde colocar el nuevo límite Suspense, qué perfil cacheLife preguntar al usuario) es una decisión de criterio que debes pensar. El modo de planificación fuerza una propuesta coherente antes de tocar código y le da al usuario la oportunidad de redirigir cualquiera de esas decisiones.
sin cáscara, retirada (compartido)
Las palancas asumen que existe una cáscara para expandir o cachear hacia ella. Si la ruta está completamente bloqueada — HTTP 500 con blocking-route o NEXT_STATIC_GEN_BAILOUT en mcp get_logs, o cero límites Suspense en una página visiblemente renderizada — no hay cáscara. Descubre el bloqueador estructural y detente; el usuario debe envolver el acceso dinámico problemático en <Suspense> antes de que cualquiera de los bucles pueda ayudar.
verificar requiere un delta visible (compartido)
Cada bucle captura una captura de pantalla base de la cáscara antes de aplicar cualquier cambio, luego vuelve a capturar después. Reporta ambas rutas en el resumen final para que el usuario pueda ver qué cambió. Las dos capturas deben diferir visiblemente — área de reserva reducida, contenido promovido a la superficie estática, reserva objetivo desaparecida o con forma de contenido. Capturas idénticas significan que la refactorización no funcionó; deshacer. "Compila limpiamente" no es el estándar.
Oculta la superposición de desarrollo antes de cada captura de pantalla. La superposición de desarrollo de Next.js (<nextjs-portal> en la raíz del documento) renderiza guía de navegación instantánea, errores de compilación y otro chrome de desarrollo que contamina la comparación antes/después. Ocúltala, captura la pantalla, restaura:
agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <ruta>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"
antipatrones (compartido)
No reemplaces límites Suspense granulares con un esqueleto de carga de nivel superior. Un loading.tsx para todo el segmento, o un <Suspense fallback={<Skeleton />}> a nivel raíz (o peor, fallback={null} que deja la interfaz en blanco), anula la optimización de esta habilidad — que consiste en extraer chrome estático real por encima de cada límite granular y usar reservas con forma de contenido por región. Un sustituto tosco de "la página está cargando" evita el trabajo por completo.
errores comunes (compartido)
- Dev no precarga como lo hace producción, y las rutas se compilan en el primer golpe — así que después de una navegación o recarga, el DOM sigue actualizándose notablemente más tiempo que la experiencia eventual de producción. Espera pacientemente a que el DOM se estabilice antes de capturar el árbol React o tomar una captura de pantalla — por ejemplo, consulta
document.documentElement.innerHTML.lengthhasta que no cambie en dos lecturas consecutivas. Un retraso corto fijo corre el riesgo de muestrear a mitad de renderizado. - No intentes verificar la precarga de navegación inspeccionando el tráfico de red de desarrollo — dev no dispara solicitudes de precarga en absoluto, por lo que la pestaña de red, las llamadas manuales
router.prefetch()y<Link prefetch={true}>parecerán rotos independientemente de si tu código es correcto. La receta de navegación SPA bloqueada por cookie en instant-nav-loop.md bajoverifyya es la receta canónica para esto — simula lo que producción prerrenderizaría en el RSC precargado sin requerir que la precarga realmente se active. Úsala; no inventes una alternativa de pestaña de red. - El pipeline de diagnóstico puede ser inestable: el tiempo de conexión de las herramientas de desarrollo, las carreras de estabilización del DOM y los efectos de compilación de desarrollo pueden producir capturas inconsistentes de una ejecución a otra. Cuando un resultado parezca extraño (aparece un candidato que no esperas, o uno que esperas no aparece), repite el diagnóstico 2-3 veces y verifica; los límites que aparecen consistentemente son reales, las apariciones únicas son ruido.
referencia (primitivas compartidas)
agent-browser react suspense agregar --only-dynamic para filtrar
--json límites realmente suspendidos
del lado del servidor. Cada
entrada tiene jsx_source +
suspended_by[] con nombres de
bloqueador crudos (usePathname,
cookies, fetch, cache, ...);
clasificar por nombre para
reglas por bucle
POST /__nextjs_original-stack-frames body { frames: StackFrame[],
isServer, isEdgeServer,
isAppDirectory }; devuelve un
resultado por frame con
archivo:línea:columna
mcp get_logs herramienta MCP de desarrollo
de next-dev-loop; muestra
blocking-route /
NEXT_STATIC_GEN_BAILOUT 500s
cacheLife('<perfil>') default | seconds | minutes
| hours | days | weeks | max
Primitivas por bucle en instant-nav-loop.md.
limpieza (compartida)
Elimina la cookie por nombre — sobrescríbela con un sello caducado:
agent-browser cookies set next-instant-navigation-testing x \
--url <origen> --expires 1
Nunca uses agent-browser cookies clear (sin argumentos) — borra la autenticación.
Hermana de next-dev-loop — inicia esa primero.