PRNext et Next.js : compatibilité et migration pas à pas

#Aligner la version et ses prérequis

Pour cette version, la plage Node déclarée est ^22.23.4 || ^24.22.1 || >=26.12.1. Les pairs React, React DOM et react-server-dom-webpack sont en 19.3.1. Gardez les dépendances natives facultatives activées : le composant natif doit correspondre à la version du framework.

Les commandes ci-dessous utilisent npm. Conservez pnpm ou Yarn si votre projet les utilise déjà et consultez la documentation livrée dans le paquet. Faites l’essai sur une branche ou une copie, avec le lockfile de départ conservé. Il n’est pas nécessaire d’installer Rust pour utiliser les paquets natifs publiés.

node --version
npm install --save-exact @thomas.f/prnext@0.1.18-alpha react@19.3.1 react-dom@19.3.1 react-server-dom-webpack@19.3.1
npx --no-install prnext migrate --dry-run
npx --no-install prnext migrate --check --json

#Repérer les fonctionnalités qui méritent un test

Les conventions de routage, les composants serveur, les actions, la navigation et les styles font partie des domaines adaptés par PRNext. Leur portée dépend de la configuration et du chemin exécuté. La matrice suivante indique quoi vérifier dans l’application, sans attribuer une compatibilité universelle à chaque famille.

#Lire le plan avant d’appliquer la migration

Le dry run permet d’examiner les changements envisagés dans les scripts et dépendances. Le contrôle doit aussi relever les conflits de configuration et de sources. Gardez un seul fichier next.config.* ou prnext.config.* ; une option Next.js inconnue ne devient pas supportée parce que son fichier a été renommé.

Lorsque le plan convient, appliquez la migration, puis contrôlez la configuration et compilez. typecheck nécessite TypeScript et un tsconfig dans l’application. La migration conserve les sources et Next.js ; les imports publics next/* peuvent rester. Ne remplacez pas tous les imports à l’aveugle et ne masquez pas un conflit de pairs avec --force.

npx --no-install prnext migrate
npx --no-install prnext check --json
npx --no-install prnext typecheck
npx --no-install prnext build

#Comparer les réponses de deux serveurs distincts

Démarrez la référence Next.js sur un port libre et le candidat sur un autre. Le fichier paths.json contient un tableau JSON de routes concrètes, par exemple ["/", "/products/demo", "/api/health"], à remplacer par celles du projet. Il ne doit pas contenir de cookies ou de secrets.

Le comparateur vérifie des échantillons de réponses GET publiques. Il n’authentifie pas les requêtes et ne suit pas les redirections. Ses temps ne sont pas un benchmark contrôlé. Un résultat favorable laisse encore à vérifier le style, l’hydratation, les mutations et les états connectés dans un navigateur.

npx --no-install prnext migrate --check --against http://127.0.0.1:3000 --candidate http://127.0.0.1:3001 --routes paths.json

#Valider les parcours qui font vivre le produit

Parcourez une connexion, une déconnexion et une action métier. Vérifiez les retours arrière, les erreurs, les chargements et les cookies. Sur un formulaire, contrôlez le résultat côté données et l’état affiché après la réponse. Le statut HTTP ne raconte pas toute l’interaction.

Ajoutez un test d’isolation avec deux sessions : aucune réponse privée ni donnée de cache ne doit passer de l’une à l’autre. Si vous utilisez des imports privés Next.js, des loaders ou un routage avancé, conservez un exemple minimal du chemin testé. Ces dépendances peuvent changer le résultat de l’essai.

#Décider après les vérifications fonctionnelles

Conservez la version exacte, le lockfile, les cas testés et les éventuelles incompatibilités. Si une fonction manque, identifiez l’API et le scénario concernés. Une réserve précise est plus utile qu’un pourcentage global de compatibilité.

Mesurez ensuite vos routes coûteuses avec les mêmes contraintes de ressources. Gardez la référence disponible tant que l’essai ne répond pas à vos critères. Une éventuelle migration de base de données demande son propre plan de retour ; restaurer un package.json ne l’annule pas.

Choisir PRNext selon les besoins de votre application

Mesurer le SSR après validation fonctionnelle