Comprendre le versionnage de librairies

Par Nael Shiab

Dernière mise à jour le 13 novembre 2026

Vous avez peut-être remarqué que les versions de librairies sur npm et dans votre fichier package.json sont accompagnées de numéros.

Par exemple, la librairie Simple Data Analysis  a publié la version 6.0.21. Cette convention de numérotation s’appelle le versionnage sémantique, ou SemVer pour faire court.

Quand les responsables d’une librairie mettent à jour ces numéros, c’est (en général 😅) pour une bonne raison et, dans cette leçon, je vais vous expliquer laquelle !

Majeure, mineure et patch

Majeure

Le premier nombre correspond à la version majeure. Dans 6.0.21, le 6 indique qu’il s’agit de la sixième version majeure de la librairie. Quand ce nombre change, cela signifie que des changements importants et incompatibles ont été introduits. Par exemple, si vous utilisez la version 5.21.1 et souhaitez passer à la version 6.0.21, vous devrez probablement modifier votre code aussi. Certaines classes, méthodes, fonctions, etc. ont été modifiées ou supprimées.

Donc si vous prévoyez de mettre à jour vers une version majeure, prévoyez toujours un peu de temps pour ajuster votre projet. Et demandez-vous toujours si ça en vaut vraiment la peine !

Encore un détail sur les versions majeures. Si la version d’une librairie commence par 0, elle en est encore à ses débuts. Le code que vous utilisez dans cette librairie peut changer à tout moment, même lors d’une mise à jour mineure ou patch.

Mineure

Le deuxième nombre correspond à la version mineure. Dans 6.0.21, c’est le 0.

Par exemple, passer de 6.0.21 à 6.1.0 est une mise à jour mineure. Une version mineure peut ajouter des fonctionnalités tout en gardant le code existant fonctionnel.

À partir de la version 1.0.0, votre code devrait continuer de fonctionner après une mise à jour mineure. Mais les mainteneurs sont humains (pour l’instant 🤖), alors il peut encore y avoir des surprises ! 😬

Patch

Le troisième nombre correspond à la version patch. Dans 6.0.21, c’est le 21.

Par exemple, passer de 6.0.20 à 6.0.21 est une mise à jour patch. Le dernier nombre passe de 20 à 21. Les versions patch sont généralement de petites mises à jour qui corrigent des bugs tout en gardant le code existant fonctionnel.

À partir de la version 1.0.0, les mises à jour patch sont généralement les plus sûres. Elles corrigent des bugs et vous ne devriez pas avoir à modifier votre code pour les utiliser.

Autres versions

Certains mainteneurs publient aussi des versions alpha, beta et rc (release candidate).

Ces versions sont disponibles à tous, mais à vos risques et périls. De nombreux bugs et changements incompatibles sont à prévoir.

^ et ~

Comme ce serait agaçant de devoir mettre à jour tout le temps les librairies pour chaque nouvelle version minor ou patch, certains projets ajoutent un préfixe ^ ou ~ devant les versions dans le fichier package.json.

Ces symboles définissent une plage de versions acceptables pour une librairie.

^ (accent circonflexe)

À partir de la version 1.0.0, ^ autorise les mises à jour mineures et patch compatibles au sein de la même version majeure.

Par exemple, @nshiab/simple-data-analysis@^6.0.0 signifie que le projet peut utiliser les versions compatibles avant v7.0.0. Donc @nshiab/simple-data-analysis@6.1.0 et @nshiab/simple-data-analysis@6.1.1 sont valides.

~ (tilde)

Le tilde (~) garde les mêmes numéros de version majeure et mineure et vous permet d’utiliser le patch indiqué ou un patch plus récent. Par exemple, ~6.0.21 autorise 6.0.21 et les versions 6.0.x suivantes. Les versions 6.0.20 et 6.1.0 sont en dehors de cette plage.

Mettre à jour ses dépendances

Vous pouvez suivre des projets et des mainteneurs sur GitHub pour rester à jour avec vos librairies préférées (voyez la leçon sur GitHub), mais npm peut aussi vérifier les dépendances de votre projet.

Exécutez npm outdated dans le terminal du projet. Voici ses principales colonnes :

• Current : la version installée localement.
• Wanted : la version la plus récente autorisée par la plage de votre package.json.
• Latest : la version marquée latest sur npm, qui peut être en dehors de cette plage.

Exécutez npm update pour mettre à jour les dépendances installées en respectant leurs plages. Cette commande met à jour package-lock.json; par défaut, elle conserve les plages de package.json.

Pour installer une version précise, exécutez une commande comme npm install @nshiab/simple-data-analysis@6.0.21. Cela met également à jour la dépendance dans package.json.

Pour fixer une dépendance à une version précise, indiquez "6.0.21" dans package.json sans accent circonflexe (^) ni tilde (~).

Conclusion

Le SemVer est utile pour comprendre les conséquences possibles d’une mise à jour de librairie. Mais n’oubliez pas que ce n’est qu’une convention. Rien n’oblige quiconque à la suivre.

TypeScript est une exception bien connue. L’équipe augmente le nombre du milieu à chaque version qui apporte des fonctionnalités. Après 9, elle passe au nombre suivant, comme de 5.9 à 6.0, qu’il y ait ou non des changements incompatibles. Une mise à jour mineure peut donc introduire des changements incompatibles ! 😱 Cependant, l’équipe fait beaucoup d’efforts pour que le code existant continue de fonctionner et prévient généralement les utilisateurs à l’avance des gros changements qui risquent de casser leur code.

Alors, avant de mettre à jour une librairie dont dépend votre code, regardez ce qui a changé depuis la version que vous utilisez. Prévoyez un peu de temps au cas où tout casserait.

Un dernier conseil : évitez de mettre à jour vos librairies juste avant une date limite ou une mise en production. Si ça fonctionne et que vous n’avez pas besoin d’une mise à jour de sécurité, n’y touchez pas. 😅