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: trueno hace nada en rutaspages/. Si el proyecto tiene un árbolpages/osrc/pages/pero noapp/osrc/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 (conpages/yapp/) está bien: la bandera afecta a las rutasapp/; las rutaspages/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:
cacheComponentsde nivel superior,export const instant, las advertencias de validación de navegación instantánea en la superposición de desarrollo y el codemodcache-components-instant-false. Sinext --versioninforma una versión inferior a 16.3, actualiza primero:- Ejecuta
npx @next/codemod@latest upgrade latestpara aplicar los codemods de versión a versión. - Lee la guía de actualización de versión correspondiente (por ejemplo, Versión 16) para lo que el codemod no cubre.
- Ejecuta
-
Sin claves de configuración incompatibles.
cacheComponents: trueda error en cualquier archivo que aún exportedynamic,revalidateofetchCache. 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 = 3600para que el bucle lo retome. El codemodcache-components-instant-falseno toca estos. -
experimental.dynamicIOes fatal. Fue renombrado acacheComponentsde nivel superior y la clave antigua ahora aborta antes de que se pueda ejecutar cualquier compilación: elimínala (o reemplázala concacheComponents: true) primero.experimental.useCachetodavía se acepta como un alias obsoleto; es redundante una vez que se establececacheComponents: 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 errorplease 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, ejecutanpx @next/codemod@latest agents-mdpara escribir un índice con la versión coincidente enAGENTS.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
cacheComponentsy 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:
- 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.paramsysearchParamsa 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 paraparams/searchParams, reenviar la promesa al hijo y esperarla allí; no hagasawaiten la parte superior de la página. - E/S síncrona en tiempo de módulo/renderizado (
new Date(),Date.now(),Math.random(),crypto.randomUUID()). Estos fallan la compilación incluso coninstant = 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 enawait 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. - Archivos
"use cache"que leen datos de solicitud. Un archivo con una directiva"use cache"de nivel superior no puede exportarinstant; combinar los dos da error conOnly 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 denext 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-pathscompila 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-prerenderdeshabilita 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:
-
next-dev-loop— fuertemente preferido. Cruza verificaciones de/_next/mcpcontra el navegador en vivo a través deagent-browsery 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 pincharnext devmanualmente.Instálalo antes de comenzar el bucle. No esperes hasta que encuentres algo que
next devsolo no pueda explicar. Ejecuta:npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loopLa skill requiere
agent-browser >= 0.27.0y te guiará a través de ello.Requiere Turbopack. Si el script
devenpackage.jsonpasa--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-loopen 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. -
Un navegador que puedas conducir tú mismo. Playwright,
agent-browserdirectamente, cualquier herramienta de automatización de navegador. Úsalo solo cuandonext-dev-loopesté 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". -
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. -
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
cacheComponentsy 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.
-
E/S síncrona en tiempo de módulo/renderizado. Busca en todo el repositorio
new Date(),Date.now(),Math.random()ycrypto.randomUUID()(no soloapp/**/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 errorblocking-prerender-*. -
Configuraciones de segmento incompatibles. Busca
^export const (revalidate|dynamic|fetchCache)enapp/y traduce según la nota derequisitosanterior. 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:
- 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 = falsede un archivo a la vez. - 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". - Verificar. Después de cada corrección, ejecuta
next dev+agent-browser/next-dev-looppara confirmar que la superposición está limpia y la ruta se comporta correctamente en tiempo de ejecución. Luego ejecutanext buildpara confirmar que la compilación pasa. Una compilación exitosa es parte de la barra de éxito por ruta. - 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 startlocalmente. - Sugerencias para el monitoreo continuo (por ejemplo, ejecutar el bucle de desarrollo periódicamente a medida que se agregan nuevas rutas).