Communitygithub.com

optimizador-cache-componentes-next

Optimiza una aplicación Next.js con `cacheComponents: true` mejorando la cáscara estática en la primera carga o la navegación entre rutas. Selecciona el bucle de diagnóstico adecuado y lo ejecuta.

¿Qué es optimizador-cache-componentes-next?

Esta habilidad para agentes IA optimiza aplicaciones Next.js que tienen `cacheComponents: true` en dos escenarios principales: la carga inicial de una ruta (bucle de renderizado de página) y la navegación entre rutas (bucle de navegación instantánea). El agente selecciona automáticamente el bucle de diagnóstico correcto basándose en la queja del usuario. Los bucles comparten palancas de refactorización como 'empujar hacia abajo' (extraer operaciones I/O en componentes envueltos en Suspense) y 'cachear' (usar `'use cache'` + `cacheLife`), y requieren que el usuario ya esté autenticado en la página relevante. La habilidad utiliza una cookie especial (`next-instant-navigation-testing`) para congelar las escrituras dinámicas del framework y capturar el estado estático. Es compatible con `next-dev-loop`, que proporciona el navegador con cabeza, la CLI `agent-browser` y el servidor MCP de desarrollo. El agente sigue un flujo de pre-vuelo, decide el bucle, aplica refactorizaciones a través de un modo de planificación, captura capturas de pantalla antes/después y verifica un delta visible; si no hay diferencia, deshace el cambio. No reemplaza límites Suspense granulares con esqueletos de carga toscos.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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 por suspended_by[].name, elimina hooks solo de SSR.

Elige uno y ejecútalo de principio a fin.

requiere

  • next-dev-loop iniciado para esta sesión — abre el navegador con cabeza, expone la CLI agent-browser y conecta el servidor MCP de desarrollo que proporciona mcp get_logs.
  • cacheComponents: true en next.config.ts. Recházalo si no.

prevuelo (compartido)

  1. Confirma cacheComponents: true.
  2. 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).
  3. agent-browser get url para 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.length hasta 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 bajo verify ya 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.

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 relacionados