Compatibilité et dépréciation — ce que vous risquez en montant de version

stablemis à jour 2026-10-03

📍 Documentation › Guides › Compatibilité

Avant d’adopter une dépendance, on se pose trois questions : qu’est-ce qui peut casser, quand on me préviendra, et combien de temps l’ancienne version vivra. Cette page y répond pour Nodefony, sans détour et sans promesse que le projet ne pourrait pas tenir.

Deux principes la gouvernent :

• Ce qui n’est pas déclaré public n’est pas public. La surface couverte par le versionnage est celle que les paquets exposent explicitement — rien de plus.
• Une politique qu’on enfreint fait plus de dégâts que pas de politique. Les engagements ci-dessous sont volontairement étroits ; ils sont tenus.

Ce qui est couvert, et ce qui ne l’est pas#

Nodefony suit semver 2.0.0. La garantie porte uniquement sur ce qu’un paquet déclare dans le champ exports de son package.json.

Pour savoir ce qu’un paquet expose, la source fait foi et se lit en une commande :

npm view @nodefony/http exports        # ce que le paquet PUBLIÉ déclare

Le comportement compte autant que la signature. Un changement qui ne modifie aucun type mais casse un usage raisonnable — un code d’erreur qui change, un défaut de configuration inversé, un en-tête qui disparaît — est traité comme une rupture, pas comme un correctif.

Les versions vont par quinze#

Tous les paquets publiés partagent la même version, publiée d’un seul lot. Il n’existe pas de @nodefony/http@10.1 compatible avec @nodefony/framework@10.0 : les combinaisons croisées ne sont ni testées ni supportées.

Ce que ça change pour vous, concrètement : montez les paquets Nodefony ensemble. Si votre gestionnaire de dépendances vous propose de n’en mettre qu’un à jour, ne le faites pas.

npm update nodefony @nodefony/http @nodefony/framework   # ensemble, jamais l'un sans l'autre

Ce qu’une version veut dire#

Relever le plancher Node est une version majeure. Passer de Node 24 à Node 26 casse l’installation de qui n’a pas migré : c’est une rupture, même si pas une ligne de code n’a changé. Le plancher courant se lit dans le paquet lui-même :

npm view nodefony engines.node

Navigateurs : la cible du client#

Le code que Nodefony livre au navigateur (nodefony/client, le temps réel, le journal, la barre de debug) est écrit et compilé pour ES2022, sans transpilation ni polyfill. Il demande donc un navigateur qui implémente ES2022 en entier : Chrome et Edge 94+, Firefox 93+, Safari 16.4+.

Relever cette cible est une version majeure, comme relever le plancher Node : un navigateur qui affichait votre application cesserait de le faire. L’abaisser, en revanche, ne casse rien.

La cible est tenue par le compilateur, pas par une relecture : le code client se vérifie avec la seule bibliothèque standard ES2022 (tsconfigClient.json, lib). Une API plus récente — Array.prototype.findLast, Promise.withResolvers… — y est refusée à la compilation. Monter de cible est donc une décision explicite, prise au changelog, jamais l’effet d’une ligne de code.

Viser un appareil plus ancien — téléviseur connecté, borne, Chromium figé d’un équipement — se règle dans votre application, pas dans le framework. Le build de production passe alors par @vitejs/plugin-legacy, qui réécrit la syntaxe et embarque les polyfills nécessaires (dont Object.hasOwn). Le serveur de développement de Vite exige, lui, un navigateur récent : le rechargement à chaud ne se teste pas sur ces appareils.

Une page ouverte en http:// par une adresse du réseau local (un téléphone, une tablette sur le réseau du poste) n’est pas un contexte sécurisé. Nodefony y fonctionne — ses identifiants client se replient sur crypto.getRandomValues — mais les API que le navigateur réserve au contexte sécurisé (caméra et micro, presse-papiers, crypto.randomUUID) y restent absentes. Servez la page en HTTPS pour les obtenir.

Le cycle de dépréciation#

Rien de public ne disparaît sans avoir été annoncé déprécié dans une version mineure au moins une fois.

1. Dépréciation — la fonction, l’option ou le comportement est marqué @deprecated dans le code publié, avec ce qu’il faut utiliser à la place. Votre éditeur le barre à l’écran : le marqueur voyage dans les fichiers de types (.d.ts) livrés avec le paquet, il n’est pas seulement un commentaire du dépôt. L’entrée figure au changelog sous Changed.
2. Vie normale — la chose dépréciée continue de fonctionner à l’identique pendant toute la série majeure. Une dépréciation n’est jamais un retrait déguisé.
3. Retrait — à la majeure suivante, et jamais avant. Le changelog l’annonce sous Removed, en tête de section.

Jamais de retrait en version mineure ni en correctif. Si vous voyez une API publique disparaître sans être passée par l’étape 1, c’est un défaut : ouvrez une issue.

Ce que Nodefony ne fait pas (encore) : émettre un avertissement à l’exécution quand du code déprécié est appelé. Aujourd’hui la dépréciation se voit à l’écriture — dans l’éditeur et au changelog — pas au démarrage. Le dire plutôt que le laisser supposer : une politique n’est utile que si elle décrit l’outillage réel.

Combien de temps une version est maintenue#

Seule la dernière version majeure reçoit des correctifs.

Dès que 11.0.0 sort, la série 10.x cesse de recevoir des correctifs — y compris de sécurité. Elle reste téléchargeable indéfiniment sur npm, mais elle n’est plus suivie.

C’est une politique étroite, et c’est délibéré. Nodefony est développé par une seule personne, sans financement : promettre douze mois de rétroportages produirait un engagement qui serait rompu au premier trimestre chargé. Mieux vaut une règle courte et vraie qu’une garantie confortable et fausse — vous pouvez planifier sur celle-ci.

Ce que ça implique pour vous :

• Prévoyez la montée de majeure comme une tâche récurrente, pas comme un imprévu.
• Les majeures ne sortent pas au hasard : une rupture est toujours motivée et documentée.
• Si vous devez rester sur une version ancienne, la licence Apache 2.0 vous autorise pleinement à la maintenir vous-même — le code est là, et les correctifs sont publics.

Signaler une rupture non annoncée#

Une rupture qui n’est pas passée par le cycle ci-dessus est un défaut de notre côté, pas une fatalité de votre côté. Ouvrez une issue avec la version d’où vous venez, celle où vous allez, et le code qui fonctionnait avant. C’est le retour le plus utile que puisse recevoir ce projet.

📖 Lexique#

⚠️ Pièges#

• La garantie porte sur exports, pas sur ce qui est atteignable. Un chemin interne accessible parce que rien ne l’interdit techniquement n’est pas public : il peut disparaître dans une version corrective, et ce ne sera pas une rupture.
• Une signature inchangée ne veut pas dire un comportement inchangé. Un code d’erreur, un en-tête retiré, un défaut inversé cassent votre code sans que le typage bouge d’une ligne.
• Seule la dernière majeure reçoit des correctifs, sécurité comprise. Il n’y a pas de rétroportage : ce projet n’a pas les moyens d’une politique qu’il ne tiendrait pas.
• Une dépréciation se lit dans votre éditeur, pas dans le changelog. Elle est portée par le TSDoc, qui traverse le build jusqu’aux types publiés — d’où le nom barré dans l’autocomplétion.
• Un vieux navigateur n’est pas un défaut de Nodefony. En deçà d’ES2022, l’application s’adapte par @vitejs/plugin-legacy au build ; le framework ne transpile pas son code client pour vous.
• Rien ne vous oblige à monter les quinze paquets en même temps, mais rien ne garantit qu’un mélange fonctionne : les versions sont conçues, testées et publiées ensemble.

🧪 Tests & couverture#

Ce qui protège la surface publique est vérifié à chaque exécution — les chiffres exacts vivent dans la carte de l’aperçu, jamais figés ici.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : Guides · Toute la documentation
• 📦 La chaîne côté mainteneur, et ce que chaque garde refuse : publier une release
• ⚙️ Ce qui se configure sans toucher au code : configuration.md
• 🐳 Monter de version en conteneur : docker-cloud-native.md
• 📖 Lexique général du framework.