next-upgrade

Visión general de la skill next-upgrade

Qué hace next-upgrade

La skill next-upgrade ayuda a un agente a actualizar un proyecto real de Next.js a una versión mayor más reciente usando las guías oficiales de migración y los codemods, en lugar de improvisar a partir de la memoria. Su función es práctica: detectar la versión actual de next en tu app, trazar la ruta de actualización más segura, aplicar primero los codemods adecuados y después actualizar dependencias y revisar los breaking changes que aún requieran cambios manuales.

Quién debería usar esta skill next-upgrade

Esta skill encaja mejor con desarrolladores que mantienen un código existente de Next.js y quieren que un asistente de IA planifique o ejecute una actualización con menos desviaciones respecto a la guía oficial. Resulta especialmente útil cuando:

• tu proyecto está atrasado más de una versión mayor
• quieres un plan de actualización consciente del repositorio, no una checklist genérica
• necesitas ayuda para identificar codemods específicos por versión y alinear dependencias
• quieres soporte dentro de un flujo de Code Editing, no solo un resumen en el navegador

El trabajo real que resuelve

La mayoría de usuarios no necesitan “información sobre actualizaciones de Next.js”. Necesitan pasar de una app que hoy funciona a una versión más nueva de Next.js sin romper el routing, la compatibilidad con React, la salida de build ni las APIs de runtime. La skill next-upgrade está pensada precisamente para esa ruta de decisión y ejecución.

Qué diferencia a next-upgrade de un prompt normal

Un prompt simple puede sugerir consejos generales de actualización. next-upgrade es más acotada y más útil porque se estructura en torno a:

• leer primero tu package.json
• consultar las guías oficiales de actualización de Next.js para la versión objetivo
• gestionar los saltos de versión mayor de forma incremental
• priorizar los codemods oficiales antes de los cambios manuales
• actualizar next, react y react-dom de forma correcta y coordinada

Lo que no hace por ti

La skill no elimina la necesidad de validar el resultado. Puede guiar cambios de código y actualizaciones de dependencias, pero igualmente tienes que ejecutar tu app, las pruebas, el linting y las comprobaciones de build. Tampoco sustituye el conocimiento específico del framework en configuraciones muy personalizadas, como monorepos, integraciones poco comunes con bundlers o comportamientos de servidor/runtime profundamente modificados.

Cómo usar la skill next-upgrade

Contexto de instalación para next-upgrade

Instala la skill en tu entorno de programación con IA para poder invocarla mientras trabajas dentro del repositorio que quieres actualizar. Un patrón habitual de instalación es:

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

Si tu entorno ya expone las skills de GitHub de vercel-labs/next-skills, puede que solo necesites llamar a next-upgrade directamente.

Cómo invocar next-upgrade en la práctica

El repositorio indica una pista de argumento [target-version], así que la forma más limpia de usarla es dar la versión deseada de forma explícita, por ejemplo:

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

Si aún no sabes la versión objetivo, primero pide un plan:

• Use next-upgrade to inspect this repo and recommend the safest target version

Qué entrada necesita la skill

next-upgrade funciona mejor cuando el agente puede inspeccionar:

• package.json
• un lockfile como package-lock.json, pnpm-lock.yaml o yarn.lock
• la configuración del workspace si la app está dentro de un monorepo
• la estructura de directorios de la app, especialmente si usas app/ o pages/
• los comandos de CI o build que se usan para verificar la actualización

Entrada mínima útil:

• versión actual de Next.js
• package manager
• versión objetivo deseada
• si quieres solo planificación o cambios reales en el código

Cómo convertir un objetivo impreciso en un buen prompt para next-upgrade

Prompt débil:

• Upgrade my app

Mejor prompt:

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

El mejor prompt cuando tu repo no es trivial:

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

Esa especificidad adicional mejora el resultado porque la propia skill es concisa; tu prompt es el que aporta los límites del repo, el package manager y el alcance de la ejecución.

Flujo recomendado antes de hacer cambios

Un flujo fiable de next-upgrade usage es:

1. inspeccionar package.json y las versiones actuales de dependencias
2. elegir la versión objetivo
3. recuperar la guía oficial de actualización de Next.js para cada salto mayor implicado
4. ejecutar los codemods antes de la limpieza manual
5. actualizar next, react y react-dom
6. ejecutar lint, typecheck, tests y build de producción
7. corregir los breaking changes restantes que aparezcan en la guía o en errores de runtime

Si vas varias versiones por detrás, no des el salto a ciegas. Pide al agente que trate 13 -> 14 -> 15 -> 16 como pasos de actualización separados.

Archivo del repositorio que conviene leer primero

Empieza por skills/next-upgrade/SKILL.md en el repositorio upstream:

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

Es una skill breve, así que no hay muchos archivos de apoyo que inspeccionar. El valor principal está en el flujo de trabajo codificado en SKILL.md: detectar la versión, obtener la documentación oficial, actualizar de forma incremental, ejecutar primero los codemods y luego actualizar dependencias.

Documentación oficial de la que depende esta skill

La skill apunta explícitamente a recursos oficiales de actualización de Next.js, incluidos:

• codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
• guías por versión como:
  • https://nextjs.org/docs/app/guides/upgrading/version-16
  • https://nextjs.org/docs/app/guides/upgrading/version-15
  • https://nextjs.org/docs/app/guides/upgrading/version-14

Esto importa a la hora de decidir si adoptarla: next-upgrade solo es tan buena como la disposición del agente a consultar y seguir esas guías, en vez de apoyarse en conocimiento desactualizado del framework.

En next-upgrade, los codemods van primero, no al final

Uno de los puntos más sólidos de la next-upgrade guide es la secuencia de trabajo. Indica al agente que ejecute pronto los codemods oficiales:
npx @next/codemod@latest <transform> <path>

Entre los ejemplos que expone la skill están:

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

Ese orden importa porque los codemods suelen resolver cambios repetitivos derivados de breaking changes de forma más rápida y segura que editar a mano después de subir versiones de dependencias.

Actualizaciones de dependencias que conviene pedir explícitamente

Al usar next-upgrade, pide al agente que actualice en conjunto las peer dependencies. La skill pone el foco específicamente en este patrón:
npm install next@latest react@latest react-dom@latest

Aunque uses pnpm o yarn, la idea se mantiene: trata next, react y react-dom como un conjunto coordinado, salvo que la guía oficial indique lo contrario.

next-upgrade para Code Editing

En tareas de Code Editing, next-upgrade es más útil cuando dejas que el agente inspeccione y modifique archivos, no solo que produzca un plan. Buenas tareas aquí incluyen:

• actualizar rangos de dependencias en package.json
• aplicar comandos de codemod
• cambiar APIs afectadas por breaking changes
• dejar comentarios inline o un resumen de migración para revisión manual

Resulta menos útil si tu entorno no puede acceder a los archivos del repositorio ni a documentación externa, porque la ventaja de la skill viene de combinar inspección del repo con recuperación de la guía oficial.

Restricciones prácticas y tradeoffs

Usa next-upgrade cuando quieras una ruta disciplinada, pero contando con algunos límites:

• no codifica localmente todos los matices de cada versión; espera consultar guías en vivo
• funciona mejor con apps estándar de Next.js que con infraestructura muy personalizada
• no incluye automatización integrada de pruebas específica de tu proyecto
• puede necesitar instrucciones adicionales en monorepos, subapps o paquetes cuyo package.json no esté en la raíz

En resumen, la skill reduce las suposiciones, pero tu prompt sigue teniendo que definir bien el alcance.

Preguntas frecuentes sobre la skill next-upgrade

¿Es next-upgrade mejor que un prompt genérico de actualización?

Por lo general, sí, si buscas un proceso de actualización repetible. Un prompt genérico puede producir recomendaciones plausibles pero desactualizadas. next-upgrade se apoya en las guías oficiales de migración, los codemods y la detección de versión a partir de los archivos de tu proyecto.

¿La skill next-upgrade es apta para principiantes?

Sí, con una salvedad: los principiantes deberían usarla primero en modo de planificación. Pide:

• detección de la versión actual
• recomendación de versión objetivo
• codemods que conviene ejecutar
• cambios manuales probables
• checklist de verificación

Eso hace que la salida sea más fácil de revisar antes de permitir cambios.

¿Necesito saber primero la versión objetivo?

No. Puedes pedir a next-upgrade que inspeccione el repo y recomiende la versión objetivo más segura. Pero si ya sabes que necesitas una versión concreta por motivos de plataforma o dependencias, indicar el objetivo desde el principio produce un plan más limpio.

¿Cuándo no debería usar next-upgrade?

Omite next-upgrade si:

• estás creando una app nueva en lugar de actualizar una existente
• tu problema no está relacionado con una migración de versión
• tu stack depende de internals personalizados que no cubre la documentación oficial
• solo necesitas un comando de una línea y ya conoces exactamente la ruta de versiones

¿Puede next-upgrade gestionar saltos de varias versiones?

Sí, pero debería hacerlo de forma incremental. La skill favorece explícitamente las actualizaciones mayores paso a paso en lugar de un salto único y ciego. Si tu app está muy atrasada, pide un plan por fases y puntos de control tras cada versión mayor.

¿Funciona solo para proyectos con app router?

No, pero las guías oficiales que consulta pueden poner más énfasis en patrones más recientes de Next.js. Si tu base de código sigue usando convenciones antiguas, pide al agente que identifique qué partes de la guía aplican y cuáles no antes de editar nada.

Cómo mejorar la skill next-upgrade

Dale a next-upgrade límites de repositorio más claros

La forma más rápida de mejorar resultados es decirle al agente exactamente dónde vive la app de Next.js. En un monorepo, especifica:

• la ruta de la app, por ejemplo apps/web
• el package manager
• la herramienta de workspace
• si los cambios deben quedarse solo dentro de esa app

Sin eso, la skill puede inspeccionar el package.json equivocado o proponer comandos en el nivel incorrecto.

Pide una salida en dos fases

Un patrón sólido es:

1. solo plan
2. ejecutar cambios

Ejemplo:

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

Esto reduce ediciones accidentales demasiado amplias y hace que la skill resulte más fiable en codebases de producción.

Aporta criterios de verificación más fuertes

No pidas solo “actualizar con éxito”. Pide al agente que verifique con comandos concretos como:

• install
• lint
• typecheck
• unit tests
• production build

Esto mejora next-upgrade usage porque el agente puede optimizar para dejar el repo pasando comprobaciones, no solo con líneas de dependencias actualizadas.

Nombra los modos de fallo que te preocupan

Si tu prioridad es evitar regresiones concretas, dilo. Por ejemplo:

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

Estas restricciones guían mejores cambios que una petición amplia del tipo “haz que funcione”.

Pide la justificación de la selección de codemods

Un prompt de mejora útil es:

• List which @next/codemod transforms apply to this repo and why before running them

Esto te ayuda a revisar si el agente está relacionando los transforms con patrones reales del código, en lugar de ejecutar codemods indiscriminadamente.

Fallos habituales al usar next-upgrade

Patrones típicos de resultados flojos incluyen:

• actualizar dependencias sin comprobar primero la versión actual
• saltarse versiones mayores intermedias
• editar a mano antes de revisar los codemods
• ignorar la alineación entre react y react-dom
• asumir que el package.json de la raíz es el de la app en un monorepo

Si ves alguno de estos casos, para y pide un plan versión por versión.

Cómo iterar después de la primera salida

Después de la primera pasada, pide una segunda más precisa centrada en lo que falló:

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

Esto funciona mejor que empezar de cero porque la skill está diseñada en torno a pasos de migración, no a una perfección instantánea de una sola vez.

Mejor patrón de prompt para obtener resultados de mayor calidad con next-upgrade

Una plantilla compacta y de alta señal:

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

Ese prompt da a la next-upgrade skill la estructura suficiente para producir un resultado materialmente mejor que una solicitud genérica de Code Editing.