Monter de version — les paquets, puis l'application

stablemis à jour 2026-10-13

📍 Documentation › Guides › Monter de version

Le modèle — ce qu’un npm install ne refait pas#

Monter Nodefony de version, c’est comme changer la version d’un manuel scolaire : on remplace les livres (les paquets), mais les fiches que la classe a recopiées à la rentrée restent celles de l’ancienne édition tant que personne ne les refait. Une application générée porte trois de ces « fiches » : la page d’accueil des agents de code (AGENTS.md), les renvois vers les skills d’agent, et les fichiers que les paquets ont déposés à sa création (le décor Keycloak, par exemple). npm install ne touche à aucun des trois.

Rien ne casse pour autant — c’est bien le problème. L’application démarre, les tests passent, et un agent lâché dedans lit une porte qui décrit l’ancienne version. Cette page donne les gestes, dans l’ordre, et ce que chacun prouve.

Démarrage rapide#

Depuis la racine d’une application créée par npm create nodefony@beta :

npx nodefony outdated                      # 1. voir le retard, groupé par paquet
npm install nodefony@beta @nodefony/http@beta @nodefony/framework@beta   # 2. TOUS les paquets nodefony de l'app, même version
npx nodefony upgrade                       # 3. remettre l'application au niveau
npm run build                              # 4. reconstruire…
npx nodefony doctor                        #    …puis vérifier

Ce qu’on observe à l’étape 3, sur une application née en 10.0.0-beta.2 et montée ensuite :

Nodefony 10.0.0-beta.3 installé.

  AGENTS.md        bloc framework réécrit
  skills           3 posé(s), 1 remplacé(s)
    + nodefony-authentication
    + nodefony-security-review
    + nodefony-troubleshoot
    ~ nodefony-protect-route
  fichiers livrés  41 rafraîchi(s)
    + docker/keycloak/import/realm.json
    …

❗ Important

Pendant la série 10, le tag beta désigne la dernière préversion ; latest sert encore l’ancienne lignée 7, en JavaScript. Un npm install nodefony sans tag installe donc la 7.

Étape par étape#

1. Voir le retard#

nodefony outdated interroge npm une seule fois, à la racine, et regroupe le résultat par paquet. Il distingue une plage épinglée (où npm update ne fera rien : c’est la plage qu’il faut changer) d’un simple retard.

2. Monter les paquets ensemble#

Les paquets Nodefony sortent verrouillés : nodefony et chaque @nodefony/* portent la même version, conçue, testée et publiée ensemble. Montez-les dans la même commande, en nommant chacun de ceux que votre package.json déclare — y compris en devDependencies (@nodefony/devkit). Un mélange de versions n’est pas garanti ; la politique complète est dans Compatibilité.

3. Remettre l’application au niveau — nodefony upgrade#

La commande rejoue trois gestes, chacun par l’implémentation qui le fait déjà ailleurs :

Le tout est orchestré par runUpgrade() (upgrade.ts#runUpgrade). Ce que la commande ne tranche pas — une copie retouchée, un skill écrit à la main, un pointeur orphelin — est nommé sous « À trancher à la main », jamais tu.

Elle ne démarre pas l’application et n’installe rien : elle sert précisément au moment où le dist/ n’a pas encore été reconstruit sur les nouveaux paquets.

4. Reconstruire et vérifier#

npm run build recompile l’application contre les nouveaux paquets. nodefony doctor le confirme : sa famille « Fraîcheur du build » signale désormais un bloc d’AGENTS.md ou des pointeurs de skills en retard — checkAgentsGuide() (freshness.ts#checkAgentsGuide), qui appelle le même jugement que upgrade en simulation — en nommant nodefony upgrade comme geste. Si le changelog annonce un changement de schéma, appliquez ensuite les migrations (nodefony orm:migrate).

En intégration continue#

nodefony upgrade --check n’écrit rien et sort en 1 si un des trois gestes reste à faire — isUpgradePending() (upgrade.ts#isUpgradePending) en décide. Placé dans la CI, il refuse une branche qui a monté ses paquets sans remettre l’application au niveau :

npx nodefony upgrade --check   # 0 : au niveau · 1 : en retard (le rapport dit quoi)

Une copie retouchée ou un AGENTS.md absent ne le font pas échouer : aucun des deux ne se corrige sans décision humaine, et une vérification qui rougirait pour eux ne passerait plus jamais.

📖 Lexique#

⚠️ Pièges#

• npm install nodefony sans tag installe la 7. Pendant la série 10, écrivez toujours @beta (ou la version exacte).
• Monter un seul paquet n’est pas monter Nodefony. @nodefony/devkit, en devDependencies, s’oublie facilement — c’est lui qui livre les skills d’agent.
• Un vert ne prouve pas qu’un agent lit la bonne porte. Le bloc périmé ne fait échouer aucun test : c’est nodefony doctor, ou upgrade --check en CI, qui le voit.
• upgrade ne recrée pas un AGENTS.md supprimé. L’absence peut être un choix ; il le dit et passe.
• Dans un monorepo de paquets (workspaces packages/@scope/*), l’AGENTS.md racine décrit le dépôt et s’écrit à la main : upgrade n’y touche pas.

🧪 Tests & couverture#

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : Guides · Toute la documentation
• 🤝 Ce qui peut casser en montant, et la politique de dépréciation : Compatibilité
• 🐳 Monter de version en conteneur : docker-cloud-native.md
• 📖 Lexique général du framework.