Publier sur npm et gérer le versionnage sémantique

Avant de publier, exécutez toujours npm publish --dry-run. Cette commande simule la publication sans rien téléverser réellement et vous montre précisément quels fichiers seraient inclus, leur taille ainsi que le contenu de l’archive tar du paquet. Elle permet de détecter les erreurs courantes, comme l’inclusion accidentelle de fichiers source ou l’absence du répertoire dist.

Contrôlez ce qui est publié à l’aide du champ files de package.json : "files": ["dist", "README.md"]. Cette approche par liste blanche est plus sûre que .npmignore, qui fonctionne comme une liste noire et peut laisser fuiter des fichiers sensibles si vous oubliez de les y ajouter. Incluez toujours dist, les déclarations de types et la documentation. N’incluez jamais src, les tests ou node_modules.

Les paquets npm suivent le versionnage sémantique (semver) : MAJOR.MINOR.PATCH. Incrémentez MAJOR pour les changements incompatibles, comme la suppression de propriétés ou la modification des signatures de l’API. Incrémentez MINOR pour les nouvelles fonctionnalités rétrocompatibles, comme de nouveaux composants ou de nouvelles propriétés facultatives. Incrémentez PATCH pour les corrections de bogues rétrocompatibles. La version 0.x.x est considérée comme pré-stable : tout peut encore y devenir incompatible.

Les identifiants de préversion indiquent qu’une version n’est pas prête pour la production : 1.0.0-alpha.1 pour les premières versions expérimentales, 1.0.0-beta.2 pour les versions dont les fonctionnalités sont terminées mais qui peuvent encore contenir des bogues, et 1.0.0-rc.1 (version candidate) pour les versions prêtes à être testées une dernière fois. Publiez les préversions avec npm publish --tag beta afin qu’elles ne deviennent pas l’installation par défaut.

Changesets est l’outil standard de gestion du versionnage des paquets et des journaux des modifications dans les bibliothèques de composants. Processus : les contributeurs exécutent yarn changeset add pour consigner les modifications et leur type (major/minor/patch). L’intégration continue exécute yarn changeset version pour augmenter les versions des paquets. La publication exécute yarn changeset publish pour les publier sur npm.

Changesets génère et entretient automatiquement CHANGELOG.md à partir des fichiers de modifications validés par les contributeurs. Chaque entrée comprend le numéro de version, la date de publication et la description des modifications. Vous obtenez ainsi un historique lisible de chaque version sans devoir entretenir manuellement le journal des modifications.

semantic-release est un outil de versionnage entièrement automatisé qui détermine la prochaine version à partir de messages de commit conventionnels (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Il augmente la version, génère le journal des modifications et publie sur npm — le tout étant déclenché par l’intégration continue lors de la fusion dans main. Aucune gestion manuelle des versions.

Les paquets sans portée (my-component) sont toujours publics. Les paquets à portée (@myorg/my-component) sont restreints (privés) par défaut : rendez-les publics avec npm publish --access public. Les paquets restreints nécessitent un compte npm payant ou une organisation. Vérifiez les paramètres d’accès avant votre première publication.

La provenance npm relie votre paquet publié à son commit git précis de manière vérifiable. Activez-la avec npm publish --provenance dans GitHub Actions. Les utilisateurs peuvent vérifier que le paquet installé a été construit à partir du commit source exact affiché sur la page du registre npm. Cela renforce considérablement la sécurité de la chaîne logistique logicielle.

Lorsqu’une version contient un bogue critique ou un changement incompatible, dépréciez-la : npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm affiche un avertissement de dépréciation à toute personne qui installe cette version. Cela ne supprime pas la version — npm ne supprime pas par défaut les versions publiées — mais avertit les utilisateurs qu’ils doivent effectuer une mise à niveau.

Les paquets à portée utilisent le format @scope/package-name. La portée correspond généralement à votre nom d’utilisateur npm ou au nom de votre organisation. Les paquets à portée indiquent clairement qui en assure la maintenance et évitent les conflits de noms avec les paquets sans portée. Utilisez des paquets à portée pour les paquets privés ainsi que pour les paquets à code source ouvert associés à votre organisation.

Utilisez npm publish --dry-run pour prévisualiser la publication et le champ des fichiers pour contrôler ce qui est publié. Versionnage sémantique : MAJOR pour les changements incompatibles, MINOR pour les nouvelles fonctionnalités, PATCH pour les corrections. Les préversions utilisent les balises -alpha/-beta/-rc. Changesets automatise le versionnage et la génération de CHANGELOG pour les bibliothèques développées en équipe. semantic-release automatise le processus à partir des commits conventionnels. Activez --provenance pour renforcer la sécurité de la chaîne logistique logicielle. Dépréciez les versions défectueuses avec npm deprecate.