Communitygithub.com

0n6k4v-Coder/skills

Activa los Componentes de Caché en una aplicación Next.js y resuelve las rutas bloqueantes que surgen. Úsalo cuando el usuario quiera habilitar, adoptar o migrar a Componentes de Caché, activar la bandera `cacheComponents`, trabajar a través de una avalancha de errores de bloqueo-prerender / validación instantánea, ejecutar el codemod `cache-components-instant-false`, o decidir entre optar por rutas con `export const instant = false` y corregirlas en su lugar.

¿Qué es skills?

Esta skill automatiza la adopción de Componentes de Caché (Cache Components) en aplicaciones Next.js que utilizan App Router. Permite activar la bandera `cacheComponents: true`, requerida desde Next.js 16.3, y guía al desarrollador a través del proceso de migración de rutas, manejando errores de prerenderización bloqueante y validación instantánea. Soporta dos estrategias: Incremental, que aplica primero un codemod para silenciar errores y luego adopta rutas una por una en PRs separados, y Directa, que aborda las rutas bloqueantes directamente. La skill se integra con `next dev` para depuración interactiva y `next build` para verificación final, y recomienda el uso del skill complementario `next-dev-loop` para una verificación más completa en tiempo de ejecución. También incluye pasos para manejar configuraciones incompatibles (como `dynamic`, `revalidate`, `fetchCache`) y llamadas síncronas de E/S que el codemod no puede resolver.

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

Preguntar en tu IA favorita

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

Documentación

next-cache-components-adoption

Habilita los Componentes de Caché en una aplicación y llévala hasta una compilación exitosa. Esta skill secuencia el trabajo; las recetas por error viven en las tarjetas de corrección de la superposición de desarrollo y en la salida del terminal de compilación. La guía de migración a Componentes de Caché es la referencia canónica para los conceptos y recetas por API que aplica esta skill; consúltala siempre que los pasos de la skill hagan referencia a un patrón ("use cache", cacheLife, colocación de <Suspense>, etc.) y quieras la explicación completa.

requisitos

  • Proyecto con App Router. Los Componentes de Caché son una característica de App Router; cacheComponents: true no hace nada en rutas pages/. Si el proyecto tiene un árbol pages/ o src/pages/ pero no app/ o src/app/, detente e informa al usuario: la migración de Pages a App es un proyecto aparte, no parte de esta skill. Una aplicación híbrida (con pages/ y app/) está bien: la bandera afecta a las rutas app/; las rutas pages/ no se ven afectadas y no necesitan exclusión.

  • Next.js 16.3 o posterior. Esa versión es donde llegan las piezas de las que depende esta skill: cacheComponents de nivel superior, export const instant, las advertencias de validación de navegación instantánea en la superposición de desarrollo y el codemod cache-components-instant-false. Si next --version informa una versión inferior a 16.3, actualiza primero:

  • Sin claves de configuración incompatibles. cacheComponents: true da error en cualquier archivo que aún exporte dynamic, revalidate o fetchCache. Traduce, no elimines. Cada exportación codifica un comportamiento que la ruta necesita seguir haciendo; migra cada una a su equivalente de Componentes de Caché a través de las secciones por clave de la guía de migración. Si un valor no se puede traducir limpiamente todavía, deja un comentario // TODO: Adopción de Componentes de Caché — restaurar revalidate = 3600 para que el bucle lo retome. El codemod cache-components-instant-false no toca estos.

  • experimental.dynamicIO es fatal. Fue renombrado a cacheComponents de nivel superior y la clave antigua ahora aborta antes de que se pueda ejecutar cualquier compilación: elimínala (o reemplázala con cacheComponents: true) primero. experimental.useCache todavía se acepta como un alias obsoleto; es redundante una vez que se establece cacheComponents: true, así que elimínalo para mayor claridad.

notas

  • Sin línea base exitosa antes de la bandera. Si la aplicación ya usa "use cache", la compilación previa a la bandera falla con el error please enable the feature flag cacheComponents. Habilitar la bandera es lo primero que haces (en Incremental, antes del codemod; en Directo, antes de corregir rutas), no algo que hacer después de obtener una compilación exitosa. Ten esto en cuenta en tu resumen inicial para que no parezca una regresión.

  • Documentación sin conexión. Las copias sin conexión de los enlaces de la guía se encuentran en node_modules/next/dist/docs/, con la estructura de directorios numerada para ordenar (por ejemplo, node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md). El nombre de archivo final coincide con el slug. Si no puedes predecir el prefijo numerado, find node_modules/next/dist/docs -name '<slug>.md' lo resuelve. Las páginas de error /docs/messages/* no están incluidas. Si faltan completamente los documentos sin conexión, ejecuta npx @next/codemod@latest agents-md para escribir un índice con la versión coincidente en AGENTS.md / CLAUDE.md.

la forma del trabajo

Hay un bucle: recorrer el árbol de rutas de arriba a abajo, una característica a la vez, adoptando cada ruta contra next dev + un navegador. La compilación es una verificación final para cada característica, no la superficie de trabajo.

La elección en el paso 1 es si silenciar primero los errores de validación o corregirlos sobre la marcha. De cualquier manera, el bucle es el mismo:

  • Con un paso previo silencioso (Incremental). Ejecuta el codemod para excluir cada página y diseño de la validación. Una vez que también hayas corregido lo que el codemod no puede (llamadas síncronas de E/S, exportaciones sobrantes de revalidate/dynamic/fetchCache), la compilación pasa; envías eso como su propio PR y luego comienzas el bucle: eliminando una exclusión a la vez y adoptando esa ruta. Divide el trabajo en pequeños PRs revisables.
  • Sin él (Directo). Habilita cacheComponents y comienza el bucle en lo que la compilación marque primero. Mismo bucle, pero cada corrección está en una rama hasta que la adopción esté completa.

En ambos, la barra de éxito por ruta es la misma: el bucle de desarrollo no informa errores Y next build pasa. Consulta con el usuario después de cada característica. Espera pasar la mayor parte del tiempo en el bucle, no en el paso previo.

antecedentes

cacheComponents: true requiere que cada ruta sea prerenderizable. Una ruta que lee datos en tiempo de solicitud fuera de <Suspense> es "bloqueante" y falla la compilación. export const instant = false marca una ruta como permitida para bloquear, lo que la limpia tanto en desarrollo como en compilación; en un diseño, cubre todo el subárbol debajo de él. Las lecturas envueltas en una función "use cache" cuentan como límites de caché, no como lecturas bloqueantes.

Tres clases de bloqueadores afectan a los agentes en este orden:

  1. Lecturas en tiempo de solicitud (cookies(), headers(), await params, await searchParams). Los cuatro bloquean cuando se esperan en la parte superior de una página o diseño. params y searchParams a menudo se pasan por alto porque no se enmarcan como "datos de solicitud" como lo hacen cookies y headers. La solución es empujar la lectura a un hijo envuelto en <Suspense> — y para params/searchParams, reenviar la promesa al hijo y esperarla allí; no hagas await en la parte superior de la página.
  2. E/S síncrona en tiempo de módulo/renderizado (new Date(), Date.now(), Math.random(), crypto.randomUUID()). Estos fallan la compilación incluso con instant = false — la exclusión no los suprime. Si están en un diseño compartido, bloquean cada ruta debajo de él. El codemod no puede corregirlos; tienes que traducir cada uno (almacenarlo en caché con "use cache" si es estable, o envolverlo en await connection() + <Suspense> si es por solicitud) antes de que la compilación pueda pasar. Busca en todo el repositorio estas llamadas antes de ejecutar cualquier otra cosa.
  3. Archivos "use cache" que leen datos de solicitud. Un archivo con una directiva "use cache" de nivel superior no puede exportar instant; combinar los dos da error con Only async functions are allowed to be exported in a "use cache" file. y significa que la directiva era incorrecta para esa ruta. Elimínala antes de ejecutar el codemod.

superficies de trabajo

encontrar rutas bloqueantes

Prefiere next dev sobre next build mientras trabajas.

  • next dev — la superficie de trabajo. Visita una ruta; sus errores de bloqueo aparecen en la superposición de desarrollo con seguimientos de pila completos y tarjetas de corrección que enlazan a la documentación por error. Trabaja una ruta a la vez: los errores no se acumulan en un solo lugar. La ruta en sí misma aún devuelve HTTP 200, así que lee la superposición (o .next-dev.log), no los códigos de estado. Una superposición limpia es la mitad de una ruta limpia: la otra mitad es la verificación del navegador (ver paso 2) y una compilación exitosa para esa ruta.
  • next build — solo detección. La compilación es la verificación autorizada de next dev, no su reemplazo. Úsala como la última puerta para cada característica en el bucle (una compilación exitosa es parte de la barra de éxito por ruta) y como la verificación final en toda la aplicación. En Incremental, la compilación también confirma el paso previo (el codemod excluyó cada ruta, ningún diseño compartido tiene aún un bloqueador de E/S síncrona) antes de enviar ese PR. No recurras a la compilación en lugar del bucle de desarrollo mientras trabajas en una ruta: un error de compilación limpio no te dice qué terminó en el shell estático frente a lo transmitido. Por defecto, la compilación se detiene en la primera ruta bloqueante, por lo que también es pobre para dimensionar el trabajo. Dos banderas ayudan al iterar: --debug-build-paths compila solo las rutas que nombres (patrones glob separados por comas de rutas de archivo relativas a la raíz del proyecto, por ejemplo --debug-build-paths="app/admin/**/page.tsx" — no rutas URL; --debug-build-paths="app/(marketing)/about/page.tsx" — no /about; --debug-build-paths="app/admin" no coincide con nada y silenciosamente compila cero rutas), y --debug-prerender deshabilita la salida anticipada para que la compilación continúe más allá del primer fallo de prerender, informe cada ruta bloqueante e imprima un seguimiento de pila más completo que nombre el archivo y la línea de origen.

Cada error de bloqueo tiene una página de documentación: ábrela. Tanto la superposición de desarrollo como el terminal de compilación imprimen un enlace https://nextjs.org/docs/messages/<slug> con cada error. Esa página es la receta canónica para la corrección; el mensaje en línea es un resumen. Obtén el enlace para cada error distinto que encuentres, incluso si crees que conoces el patrón: las recetas evolucionan y la misma clase de error puede tener diferentes correcciones correctas dependiendo de lo que lea la ruta. No improvises solo con el mensaje en línea. (Las páginas /docs/messages/* no están incluidas sin conexión; si no tienes red, recurre a las guías por API en node_modules/next/dist/docs/ y anota la limitación cuando informes.)

verificar cada corrección en tiempo de ejecución

Una compilación exitosa o una superposición limpia no es prueba de que la ruta realmente se comporte: los Componentes de Caché son una preocupación de tiempo de ejecución (un shell estático con datos transmitidos). Verifica después de cada corrección, no solo al final.

En orden de preferencia:

  1. next-dev-loop — fuertemente preferido. Cruza verificaciones de /_next/mcp contra el navegador en vivo a través de agent-browser y detecta tanto problemas de compilación como de tiempo de ejecución en una sola pasada. Los diagnósticos (árbol de React, límites de suspense, consola + red) son más ricos que pinchar next dev manualmente.

    Instálalo antes de comenzar el bucle. No esperes hasta que encuentres algo que next dev solo no pueda explicar. Ejecuta:

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

    La skill requiere agent-browser >= 0.27.0 y te guiará a través de ello.

    Requiere Turbopack. Si el script dev en package.json pasa --webpack, indícaselo al usuario y pregúntale si hay alguna razón para quedarse en webpack. Si no, cambia a Turbopack (el valor predeterminado de Next.js 16.3+). Si quieren mantener webpack, salta esta instalación y usa el bucle solo de compilación.

    No necesitas permiso para instalar next-dev-loop en sí mismo. Es una herramienta, como instalar una dependencia de desarrollo. Si un usuario está en línea, indícale brevemente que lo estás instalando para verificación. En una ejecución no interactiva (CI, panel de control, sandbox), instálalo sin preguntar: "no se puede preguntar al usuario" no es una razón para saltarlo. La única omisión legítima es un bloqueo técnico real: sin red, sin npm, sistema de archivos de solo lectura, una política declarada de no nuevas dependencias o un script de desarrollo solo para webpack. Si lo omites, nombra el bloqueador específico en tu informe final.

  2. Un navegador que puedas conducir tú mismo. Playwright, agent-browser directamente, cualquier herramienta de automatización de navegador. Úsalo solo cuando next-dev-loop esté realmente bloqueado. Te perderás las comprobaciones del lado del framework (/_next/mcp), por lo que las aserciones DOM solas no detectan todas las regresiones: sé más cauteloso sobre lo que llamas "verificado".

  3. Solo compilación. Si no puedes ejecutar un servidor de desarrollo en absoluto, la compilación es tu única señal. Las rutas ○ (Static) sin <Suspense> están completamente verificadas por la compilación (nada transmitido para probar). Las rutas ◐ (Partial Prerender) solo están verificadas en el shell: indícalo cuando informes.

  4. Sin herramientas en absoluto. Pide al usuario que ejecute el servidor de desarrollo (o la compilación) e informe lo que ve, o confirma el hito que has alcanzado y entrega.

paso 1: elegir una estrategia

Pregunta al usuario. Formúlalo como una pregunta sobre la forma del PR, no como una llamada de dimensionamiento. Nunca uses las etiquetas internas (Incremental, Directo, hito A) al hablar con el usuario — esos son tu propio andamiaje. Pregunta en términos de PRs y características, por ejemplo: "¿Quieres que primero abra un PR que active los Componentes de Caché y excluya cada ruta de la validación, y luego maneje las adopciones de rutas reales característica por característica en PRs de seguimiento? ¿O hacer todo en una sola rama?" Incluso en una aplicación pequeña, el camino incremental aún tiene valor (PR de tamaño revisable, reversible, los marcadores // TODO: Adopción de Componentes de Caché duplican tu cola de trabajo para la próxima sesión). No elijas en su nombre.

Si no hay usuario a quien preguntar, por defecto elige Incremental y documenta la elección.

  • Incremental — paso previo silencioso + el bucle. Ejecuta el codemod para excluir cada página y diseño de la validación, haz que la compilación pase, detente y consulta con el usuario (ver fin del paso previo), luego ingresa al bucle del paso 2 y envía cada característica como un PR de seguimiento.
  • Directo — salta el paso previo. Habilita cacheComponents y ve directamente al bucle del paso 2; las rutas bloqueantes de la compilación son la cola de trabajo.

incremental

Antes de invocar el codemod, corrige las dos clases de bloqueadores que no puede manejar.

  1. E/S síncrona en tiempo de módulo/renderizado. Busca en todo el repositorio new Date(), Date.now(), Math.random() y crypto.randomUUID() (no solo app/**/layout.{js,jsx,ts,tsx} — la lectura podría estar en cualquier componente importado por un diseño). Traduce cada coincidencia usando la receta de su tarjeta de error blocking-prerender-*.

  2. Configuraciones de segmento incompatibles. Busca ^export const (revalidate|dynamic|fetchCache) en app/ y traduce según la nota de requisitos anterior. El codemod no los toca; dejarlos en su lugar falla la compilación después del codemod.

El codemod se niega a ejecutarse en un árbol de trabajo sucio. Confirma o guarda el trabajo no relacionado primero, o pasa --force para permitir que sus ediciones lleguen junto con tu WIP. Falso positivo común: si actualizaste Next.js recientemente, package.json y el archivo de bloqueo ya estarán sucios; confirma esos primero.

Usa el canal @canary del codemod para obtener las últimas reglas. Ejecuta:

npx @next/codemod@canary cache-components-instant-false

Esto agrega export const instant = false a cada página y diseño, y también elimina cualquier código muerto que se haya vuelto no operativo antes de que se habilitara la bandera (sobre todo llamadas unstable_noStore y export const runtime = 'edge').

Si el proyecto usa un patrón src/, el codemod lo maneja automáticamente. Si el proyecto tiene un alcance inusual en tsconfig.json o jsconfig.json, pasa explícitamente --tsconfig y --jsconfig. El codemod solo procesa archivos en app/ y src/app/; ignora src/pages/ y pages/.

fin del paso previo: consulta

Después del codemod + correcciones manuales, confirma que no hay errores restantes de E/S síncrona que compartan un diseño (es decir, que el codemod haya recorrido con éxito las exclusiones) ejecutando una compilación. Si la compilación pasa, informa al usuario:

  • El tamaño del impacto (qué páginas/diseños se excluyeron, cuántas exportaciones/llamadas E/S síncronas se corrigieron manualmente).
  • Una solicitud para revisar el PR ("Este PR activa los Componentes de Caché y excluye todas las rutas de la validación, pero ninguna está realmente adoptada todavía — las adopciones de rutas individuales vienen en PRs de seguimiento.").
  • Si se incluye una vista previa de implementación, verifica una página representativa para confirmar que el shell se renderiza.

Si la compilación falla, informa el error y vuelve a intentar con un mensaje más claro: "El codemod agregó exclusiones, pero un diseño compartido aún emite...". Después de la confirmación, comienza el paso 2.

paso 2: el bucle interno — eliminar exclusiones una característica a la vez

El bucle consume la lista de trabajo. Característica = una pantalla que un usuario puede nombrar en una frase ("la página de inicio", "el panel de administración", "el carrito de compras"). Las páginas son los límites naturales, pero una función más grande ("el panel de administración") probablemente abarque varias: diseños anidados + páginas. Trátalo como una excepción para diseños profundos, no como la regla.

Para cada característica:

  1. Identificar el diseño/página de nivel superior. Comienza desde la raíz del árbol (el diseño raíz) y avanza hacia abajo. Elimina export const instant = false de un archivo a la vez.
  2. Aplicar recetas de corrección. Cuando encuentres un error, utiliza la tarjeta de corrección de la superposición de desarrollo, el enlace /docs/messages/<slug> o las guías de migración sin conexión para corregir la ruta. Esto generalmente implica envolver las lecturas de datos de solicitud en límites <Suspense> o funciones "use cache".
  3. Verificar. Después de cada corrección, ejecuta next dev + agent-browser/next-dev-loop para confirmar que la superposición está limpia y la ruta se comporta correctamente en tiempo de ejecución. Luego ejecuta next build para confirmar que la compilación pasa. Una compilación exitosa es parte de la barra de éxito por ruta.
  4. Avanzar. Una vez que la característica esté completamente adoptada, pasa a la siguiente característica en el bucle. Para aplicaciones Incremental, envía un PR después de cada característica; para Directo, continúa en la misma rama.

Si encuentras una ruta que no se puede corregir limpiamente (por ejemplo, una dependencia de terceros que requiere cookies() en el diseño raíz), agrega export const instant = false nuevamente y documenta la razón. La ruta permanece excluida hasta que la dependencia se pueda eliminar o refactorizar.

verificación final

Cuando se hayan adoptado todas las rutas (es decir, cada página y diseño ha eliminado su export const instant = false o se ha documentado como una exclusión intencional), ejecuta una compilación final en toda la aplicación. La compilación debe pasar sin errores de bloqueo. Si falla, revisa la salida en busca de rutas bloqueantes restantes y corrígelas.

Una vez que la compilación pase, informa al usuario:

  • El recuento final de rutas adoptadas frente a excluidas.
  • Cualquier exclusión documentada con razones.
  • Una verificación de humo de la aplicación en el entorno de vista previa o ejecutando next start localmente.
  • Sugerencias para el monitoreo continuo (por ejemplo, ejecutar el bucle de desarrollo periódicamente a medida que se agregan nuevas rutas).

Individual skills in this repo

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

Skills relacionados