next-upgrade

Présentation de la skill next-upgrade

À quoi sert next-upgrade

La skill next-upgrade aide un agent à faire évoluer un vrai projet Next.js vers une version majeure plus récente en s’appuyant sur les guides de migration officiels et les codemods, plutôt que sur des souvenirs approximatifs. Son rôle est concret : détecter la version actuelle de next dans votre application, définir le chemin de migration le plus sûr, appliquer d’abord les bons codemods, puis mettre à jour les dépendances et passer en revue les breaking changes qui demandent encore des ajustements manuels.

À qui s’adresse la skill next-upgrade

Cette skill convient surtout aux développeurs qui maintiennent une base de code Next.js existante et veulent qu’un assistant IA planifie ou exécute une migration en restant au plus près des recommandations officielles. Elle est particulièrement utile si :

• votre projet a plus d’une version majeure de retard
• vous voulez un plan de migration ancré dans le dépôt, pas une checklist générique
• vous avez besoin d’aide pour repérer les codemods propres à chaque version et aligner les dépendances
• vous voulez ce support dans un workflow de Code Editing, pas seulement un résumé dans le navigateur

Le besoin concret auquel elle répond

La plupart des utilisateurs ne cherchent pas simplement des “informations sur les mises à niveau Next.js”. Ils ont besoin de faire passer une application actuellement stable vers une version plus récente de Next.js sans casser le routing, la compatibilité React, la sortie de build ou les API d’exécution. La skill next-upgrade est pensée pour cette phase de décision puis d’exécution.

Ce qui distingue next-upgrade d’un prompt classique

Un prompt générique peut proposer des conseils de migration assez larges. next-upgrade est plus ciblée et plus utile, car elle s’organise autour de :

• la lecture de votre package.json en premier
• la vérification des guides officiels de migration Next.js pour la version cible
• la gestion des sauts de versions majeures étape par étape
• la priorité donnée aux codemods officiels avant les modifications manuelles
• la mise à niveau correcte de next, react et react-dom ensemble

Ce qu’elle ne fait pas à votre place

La skill ne supprime pas le besoin de valider le résultat. Elle peut guider les changements de code et les mises à jour de dépendances, mais vous devez toujours exécuter l’application, les tests, le linting et les vérifications de build. Ce n’est pas non plus un substitut à une connaissance fine du framework dans des configurations très personnalisées, comme les monorepos, les intégrations inhabituelles avec un bundler ou des comportements serveur/runtime fortement patchés.

Comment utiliser la skill next-upgrade

Contexte d’installation pour next-upgrade

Installez la skill dans votre environnement de développement IA afin de pouvoir l’invoquer pendant que vous travaillez dans le dépôt que vous voulez migrer. Un schéma d’installation courant est :

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

Si votre environnement expose déjà les GitHub skills de vercel-labs/next-skills, il vous suffira peut-être d’appeler next-upgrade directement.

Comment invoquer next-upgrade en pratique

Le dépôt indique un hint d’argument [target-version], donc l’usage le plus propre consiste à fournir explicitement la version visée, par exemple :

• 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 vous ne connaissez pas encore la version cible, commencez par demander un plan :

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

Quelles entrées la skill doit avoir

next-upgrade donne les meilleurs résultats lorsque l’agent peut inspecter :

• package.json
• un lockfile comme package-lock.json, pnpm-lock.yaml ou yarn.lock
• la configuration workspace si l’application vit dans un monorepo
• la structure des répertoires de l’application, en particulier si vous utilisez app/ ou pages/
• les commandes de CI ou de build utilisées pour valider la migration

Entrées minimales utiles :

• la version actuelle de Next.js
• le gestionnaire de paquets
• la version cible souhaitée
• si vous voulez seulement un plan ou de vraies modifications de code

Transformer un objectif vague en prompt next-upgrade solide

Prompt faible :

• Upgrade my app

Meilleur 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.

Meilleur prompt si votre dépôt n’est pas 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.

Ce niveau de précision améliore le résultat, car la skill elle-même reste concise ; c’est votre prompt qui fournit les limites du dépôt, le gestionnaire de paquets et le périmètre d’exécution.

Workflow recommandé avant de modifier le code

Un flux next-upgrade usage fiable ressemble à ceci :

1. inspecter package.json et les versions actuelles des dépendances
2. choisir la version cible
3. récupérer le guide officiel de mise à niveau Next.js pour chaque étape majeure concernée
4. exécuter les codemods avant le nettoyage manuel
5. mettre à jour next, react et react-dom
6. lancer le lint, le typecheck, les tests et le build de production
7. corriger les breaking changes restants signalés par le guide ou révélés par les erreurs à l’exécution

Si vous avez plusieurs versions de retard, n’effectuez pas un saut à l’aveugle. Demandez à l’agent de traiter 13 -> 14 -> 15 -> 16 comme des étapes de migration distinctes.

Fichier du dépôt à lire en premier

Commencez par skills/next-upgrade/SKILL.md dans le dépôt source :

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

La skill est courte, donc il n’y a pas beaucoup de fichiers annexes à inspecter. La valeur principale se trouve dans le workflow encodé dans SKILL.md : détecter la version, récupérer la documentation officielle, migrer progressivement, exécuter d’abord les codemods, puis mettre à jour les dépendances.

Documentation officielle dont dépend cette skill

La skill renvoie explicitement vers les ressources officielles de mise à niveau Next.js, notamment :

• codemods : https://nextjs.org/docs/app/guides/upgrading/codemods
• guides de version tels que :
  • 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

C’est important au moment de décider de l’adopter : next-upgrade n’est utile que si l’agent va réellement récupérer et suivre ces guides, au lieu de s’appuyer sur une connaissance obsolète du framework.

Avec next-upgrade, les codemods passent avant le reste

L’un des points forts du next-upgrade guide, c’est le séquençage. Il demande à l’agent d’exécuter les codemods officiels tôt dans le processus :
npx @next/codemod@latest <transform> <path>

Exemples mentionnés par la skill :

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

Cet ordre compte, car les codemods traitent souvent les breaking changes répétitives plus vite et plus sûrement qu’une retouche manuelle après la mise à niveau des dépendances.

Mises à jour de dépendances à demander explicitement

Quand vous utilisez next-upgrade, demandez à l’agent de mettre à jour ensemble les peer dependencies concernées. La skill met explicitement en avant ce schéma :
npm install next@latest react@latest react-dom@latest

Même si vous utilisez pnpm ou yarn, l’idée reste la même : considérez next, react et react-dom comme un ensemble coordonné, sauf indication contraire du guide officiel.

next-upgrade dans un workflow de Code Editing

En Code Editing, next-upgrade est surtout utile si vous laissez l’agent à la fois inspecter et modifier les fichiers, pas seulement produire un plan. Exemples de tâches pertinentes :

• mettre à jour les plages de versions dans package.json
• appliquer les commandes de codemod
• modifier les API touchées par des breaking changes
• laisser des commentaires inline ou un résumé de migration pour revue manuelle

Elle est moins utile si votre environnement n’a pas accès aux fichiers du dépôt ou à la documentation externe, car son avantage vient de la combinaison entre inspection du repo et récupération des guides officiels.

Contraintes pratiques et arbitrages

Utilisez next-upgrade si vous voulez une trajectoire disciplinée, mais gardez en tête certaines limites :

• elle n’embarque pas localement toutes les subtilités de chaque version ; elle suppose une consultation en direct des guides
• elle est plus performante sur des applications Next.js standard que sur une infrastructure très personnalisée
• elle ne fournit pas d’automatisation de tests propre à votre projet
• elle peut nécessiter un prompt plus précis pour les monorepos, les sous-applications ou les fichiers de package hors racine

En bref, la skill réduit la part de hasard, mais votre prompt doit tout de même définir clairement le périmètre.

FAQ sur la skill next-upgrade

next-upgrade est-elle meilleure qu’un prompt générique de mise à niveau ?

En général oui, si vous cherchez un processus de migration répétable. Un prompt générique peut produire des conseils plausibles mais datés. next-upgrade s’ancre dans les guides de migration officiels, les codemods et la détection de version à partir des fichiers de votre projet.

La skill next-upgrade est-elle adaptée aux débutants ?

Oui, avec une réserve : les débutants ont intérêt à l’utiliser d’abord en mode planification. Demandez :

• la détection de la version actuelle
• une recommandation de version cible
• les codemods à exécuter
• les changements manuels probables
• une checklist de validation

Le résultat sera ainsi plus simple à relire avant d’autoriser les modifications.

Faut-il connaître la version cible à l’avance ?

Non. Vous pouvez demander à next-upgrade d’inspecter le dépôt et de recommander la cible la plus sûre. Mais si vous savez déjà qu’il vous faut une version précise pour des raisons de plateforme ou de dépendances, l’indiquer dès le départ produit un plan plus net.

Dans quels cas ne pas utiliser next-upgrade ?

Évitez next-upgrade si :

• vous créez une nouvelle application au lieu d’en migrer une existante
• votre problème n’a rien à voir avec une migration de version
• votre stack dépend d’internals personnalisés non couverts par la documentation officielle
• vous avez juste besoin d’une commande en une ligne et connaissez déjà exactement le chemin de migration

next-upgrade peut-elle gérer des sauts sur plusieurs versions ?

Oui, mais de manière incrémentale. La skill privilégie explicitement les migrations majeures par étapes plutôt qu’un unique saut aveugle. Si votre application est très en retard, demandez un plan par phases avec des points de contrôle après chaque version majeure.

Fonctionne-t-elle uniquement pour les projets app router ?

Non, mais les guides officiels qu’elle va chercher peuvent davantage mettre l’accent sur les patterns récents de Next.js. Si votre base de code utilise encore des conventions plus anciennes, demandez à l’agent d’identifier quelles parties du guide s’appliquent réellement et lesquelles ne s’appliquent pas avant toute modification.

Comment améliorer la skill next-upgrade

Donner à next-upgrade des limites de dépôt plus claires

Le moyen le plus rapide d’améliorer les résultats consiste à indiquer exactement où se trouve l’application Next.js. Dans un monorepo, précisez :

• le chemin de l’application, par exemple apps/web
• le gestionnaire de paquets
• l’outil de workspace
• si les modifications doivent rester limitées à cette application

Sans cela, la skill peut inspecter le mauvais package.json ou proposer des commandes au mauvais niveau.

Demander une sortie en deux phases

Un schéma efficace consiste à demander :

1. le plan uniquement
2. l’exécution des modifications

Exemple :

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

Cela réduit le risque de modifications trop larges et rend la skill plus fiable sur des bases de code de production.

Fournir des critères de validation plus précis

Ne demandez pas simplement “upgrade successfully”. Demandez à l’agent de valider avec des commandes concrètes comme :

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

Cela améliore l’usage de next-upgrade, car l’agent peut viser un dépôt réellement valide, et pas seulement des lignes de dépendances mises à jour.

Nommer les modes d’échec qui vous préoccupent

Si votre priorité est d’éviter certaines régressions précises, dites-le explicitement. Par exemple :

• 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

Ces contraintes guident mieux les modifications qu’une demande vague du type “make it work”.

Demander la justification du choix des codemods

Un bon prompt d’amélioration est :

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

Cela vous aide à vérifier que l’agent associe les transforms aux vrais patterns du code, au lieu de lancer des codemods sans discernement.

Modes d’échec fréquents avec next-upgrade

Parmi les schémas de résultats faibles les plus courants :

• mise à jour des dépendances sans vérification préalable de la version actuelle
• saut des versions majeures intermédiaires
• retouches manuelles avant examen des codemods
• oubli de l’alignement entre react et react-dom
• supposer que le package.json racine est celui de l’application dans un monorepo

Si vous constatez l’un de ces cas, arrêtez-vous et demandez un plan version par version.

Comment itérer après le premier résultat

Après un premier passage, demandez une seconde itération plus ciblée sur ce qui a échoué :

• 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

C’est préférable à un redémarrage complet, car la skill est conçue autour d’étapes de migration, pas d’une recherche de perfection en une seule tentative.

Meilleur modèle de prompt pour des résultats next-upgrade de meilleure qualité

Un template compact et riche en signal :

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.

Ce prompt donne à la next-upgrade skill suffisamment de structure pour produire un résultat nettement meilleur qu’une demande générique de Code Editing.