Publier sur npm avec Changesets et Bun : tutoriel 2026

📍 Article principal : Bun monorepo et publication de packages

Introduction

Une agence dakaroise spécialisée dans le développement d’applications mobile money capitalise depuis deux ans une bibliothèque interne de validation et de formatage des numéros UEMOA. Pendant les premiers mois, l’équipe gérait les versions à la main : modifier le numéro dans le package.json, écrire trois lignes de changelog, taper la commande de publication. Cette procédure bricolée fonctionnait avec deux personnes mais a vite révélé ses limites quand l’équipe est passée à six développeurs : versions oubliées, changelog incomplets, releases conflictuelles. La solution adoptée — Changesets couplé à Bun et GitHub Actions — automatise tout ce processus avec une rigueur qui supporte les équipes distribuées et les rythmes de publication soutenus. Ce tutoriel installe Changesets sur un monorepo Bun existant, configure le workflow de release, et met en place la publication automatique sur npm. À la fin, chaque PR qui impacte un package public déclenche un cycle propre : changeset ajouté, validation, merge, version bumpée automatiquement, changelog mis à jour, package publié.

Prérequis

• Monorepo Bun fonctionnel (voir Configurer un workspace Bun)
• Compte npm avec accès en publication
• Dépôt GitHub avec accès Settings (pour les secrets et permissions)
• Niveau : intermédiaire — Temps : 1 h 15

Étape 1 — Installer Changesets

Changesets est une suite d’outils maintenue par Atlassian qui formalise la gestion de versions dans un monorepo. L’installation se fait à la racine du monorepo et ajoute un dossier .changeset qui contiendra la configuration et les fichiers de changement individuels. Cette structure est conçue pour bien fonctionner avec Git : chaque modification ouvre un fichier dédié, ce qui élimine les conflits de merge sur un changelog centralisé.

cd mon-monorepo
bun add -D @changesets/cli
bunx changeset init

L’init crée le fichier .changeset/config.json qui pilote le comportement par défaut. Trois options à ajuster selon le projet : "access": "public" pour les packages destinés à npm public, "baseBranch": "main" pour aligner sur la convention GitHub moderne, et "changelog" pointant vers un générateur compatible Conventional Commits si on suit cette convention. Pour la majorité des projets ouest-africains qui débutent avec Changesets, les défauts sont sains et on peut commencer sans personnalisation.

Le fichier de configuration accepte aussi des règles sur les dépendances internes — par exemple, forcer un bump de version d’un package consommateur quand son dépendance interne change. Cette option "updateInternalDependencies": "patch" évite les états incohérents où un consommateur déployé continue d’utiliser une version désuète d’un package interne. Pour les agences qui livrent des projets clients, c’est une protection précieuse.

Étape 2 — Créer un premier changeset

Le workflow Changesets repose sur l’idée que chaque modification significative d’un package est accompagnée d’un fichier markdown qui décrit l’impact (patch, minor, major selon semver) et le contenu du changement. Ce fichier est créé via une commande interactive qui guide le développeur à travers les choix : quels packages sont affectés, quel niveau d’impact pour chacun, et un résumé textuel.

bunx changeset

L’outil pose trois questions séquentielles. Quels packages sont impactés (sélection multiple via flèches et espace). Pour chaque package, quel niveau d’impact (patch pour correction de bug, minor pour ajout de fonctionnalité, major pour breaking change). Et enfin un résumé qui sera repris dans le changelog. Le fichier markdown généré dans .changeset/ a un nom aléatoire pour éviter les collisions Git et contient les métadonnées plus le résumé.

La discipline pratique : un changeset par PR significative. Les corrections triviales (faute de frappe dans un commentaire, changement de variable interne sans impact public) ne demandent pas de changeset. Les ajouts de fonctionnalité, corrections de bug, et modifications de signatures de fonctions exigent un changeset. Cette règle simple maintient la qualité du changelog sans surcharger les développeurs.

Étape 3 — Cycle de release

Une fois plusieurs changesets accumulés au fil des PR mergées, on lance le cycle de release. Deux commandes successives effectuent l’opération. La première, changeset version, agrège tous les changesets en attente, calcule les nouveaux numéros de version selon semver, met à jour les package.json concernés, génère ou met à jour les fichiers CHANGELOG.md, et supprime les changesets consommés. Cette étape ne publie rien — elle prépare uniquement les modifications à committer.

bunx changeset version
git add .
git commit -m "chore: release"
git push origin main

La seconde commande, changeset publish, exécute la publication réelle sur npm pour chaque package dont la version a été incrémentée. Elle utilise les credentials npm classiques (variable NPM_TOKEN ou login interactif) et publie un par un avec rollback automatique si l’un échoue. Cette atomicité partielle évite les états où certains packages sont publiés et d’autres non.

bunx changeset publish

Pour le développement local, ces deux commandes se lancent à la main. En CI, on les automatise comme décrit dans l’étape suivante. Le résultat est identique : versions cohérentes, changelog propre, publication atomique.

Étape 4 — Automatiser via GitHub Actions

L’automatisation repose sur l’action officielle changesets/action qui orchestre le workflow complet. Le principe : à chaque push sur main, l’action vérifie si des changesets en attente existent. Si oui, elle ouvre une PR de release qui met à jour les versions et les changelogs. Cette PR reste ouverte tant que de nouveaux changesets sont ajoutés (elle se met à jour automatiquement). Quand l’équipe décide qu’il est temps de publier, on merge cette PR et l’action déclenche la publication réelle.

La configuration GitHub Actions tient en une trentaine de lignes. On définit le déclencheur sur push: branches: [main], on configure les permissions pour permettre à l’action de créer une PR (contents: write, pull-requests: write), et on ajoute le secret NPM_TOKEN dans les paramètres du dépôt GitHub. Ce token doit être un token « automation » généré sur npm avec les permissions de publication, jamais un token personnel d’un membre de l’équipe.

Une fois l’action active, le rythme de publication devient indolore. Les développeurs ouvrent des PR, ajoutent un changeset si nécessaire, mergent. La PR de release créée par Changesets se met à jour automatiquement. Quand on veut publier — généralement une fois par semaine ou à la demande — on merge la PR de release et tout se passe automatiquement.

Étape 5 — Pré-releases et releases canary

Pour les fonctionnalités en cours de stabilisation, Changesets supporte les pré-releases. La commande changeset pre enter rc active le mode pré-release : les versions générées portent un suffixe -rc.0, -rc.1, etc., et la publication se fait avec un tag npm spécifique (npm install @itskills/shared@rc). Ce mode permet de tester en pré-production sans impacter les utilisateurs en stable.

Pour les releases canary (publication automatique de chaque commit en version pré-release), on configure un workflow GitHub Actions séparé qui génère un changeset automatique sur chaque push, lance la publication avec un tag canary, et notifie l’équipe sur Slack ou Discord. Ce pattern est utile pour les libs très utilisées en interne où l’on veut détecter les régressions avant la prochaine release stable. Pour les projets ouest-africains plus modestes, c’est généralement de l’over-engineering.

Erreurs fréquentes

Adaptation au contexte ouest-africain

Trois aspects pratiques. Premièrement, pour les agences qui veulent capitaliser leur savoir-faire technique sans forcément le rendre public, l’alternative au registre npm public est un Verdaccio interne (voir notre tutoriel dédié) qui supporte parfaitement Changesets — la seule différence est l’URL du registre dans publishConfig. L’investissement initial dans Changesets paye sur les deux scénarios (public ou privé). Deuxièmement, pour les freelances qui livrent des projets clients incluant des packages npm publics (par exemple des thèmes WordPress, des librairies de composants Vue ou Svelte), Changesets simplifie la livraison versionnée et augmente la perception de professionnalisme — un client qui voit un changelog propre et des versions semver respectées paye plus facilement les prestations suivantes. Troisièmement, pour les équipes distribuées sur plusieurs pays UEMOA, le workflow asynchrone de Changesets (chacun ajoute ses changesets sans synchronisation préalable) convient parfaitement aux décalages horaires et aux rythmes de connexion variables.

Pour le coût, npm public est gratuit pour les packages open-source et l’orga npm est gratuite jusqu’à un usage modeste. Verdaccio en alternative privée tient sur un VPS Hetzner CX22 à 5 €/mois. GitHub Actions est gratuit dans les limites du plan Free pour les dépôts publics, et 2 000 minutes/mois pour les dépôts privés — largement suffisant pour la majorité des cas d’usage.

Tutoriels frères

• Configurer un workspace Bun
• Verdaccio sur Hetzner
• CI GitHub Actions pour monorepo Bun

Pour aller plus loin

• 🔝 Pilier : Bun monorepo guide complet
• Doc : Changesets GitHub · npm publish

FAQ

Faut-il un changeset par fichier modifié ?
Non. Un changeset par PR significative suffit. Si une PR modifie plusieurs packages distincts, le changeset peut couvrir tous ces packages avec des niveaux d’impact différents.

Comment gérer les breaking changes coordonnés sur plusieurs packages ?
Un seul changeset qui marque tous les packages concernés comme major. Le changelog généré reflète le breaking change cohérent sur toute la stack.

Peut-on annuler une release publiée ?
Sur npm, npm unpublish est limité aux 72 premières heures et déconseillé (consommateurs cassés). Préférer publier immédiatement une nouvelle version corrective.

Comment auditer les publications passées ?
Les commits de release sur main et les fichiers CHANGELOG.md servent de journal. Pour un audit plus précis, npm fournit l’historique des versions par package via npm view @itskills/shared versions --json.

Stratégie de versionnement et discipline d’équipe

Au-delà de la mécanique technique, le vrai défi du versionnement en équipe est la discipline collective. Trois conventions à établir dès le démarrage. D’abord, définir explicitement ce qui constitue un breaking change pour chaque package : un changement de signature de fonction publique, un changement de format de retour, une suppression de fonctionnalité. Ces éléments imposent un major bump et donc une release planifiée avec communication préalable aux consommateurs internes. Ensuite, fixer une cadence de publication régulière : toutes les deux semaines, ou à chaque feature complétée selon le contexte. Cette régularité évite les « big bang » releases stressantes où trois mois de changements arrivent d’un coup. Enfin, instaurer une revue spécifique du changelog avant merge de la release PR — un humain valide que le résumé reflète correctement les changements et qu’aucune mention sensible n’est exposée publiquement.

Pour les SaaS qui ont des consommateurs externes (libs publiées sur npm public, ou clients qui intègrent un SDK), une politique de support des versions précédentes complète la stratégie. Annoncer publiquement combien de temps les versions majeures sont maintenues (par exemple 12 mois après sortie d’une nouvelle major), publier les correctifs de sécurité sur ces versions, et communiquer en avance des changements majeurs. Cette transparence professionnelle distingue les libs sérieuses des projets bricolés.

Alternatives à Changesets

Trois alternatives méritent considération selon le contexte. semantic-release automatise complètement les releases en analysant les messages de commit selon Conventional Commits. Plus aggressive que Changesets, elle convient aux équipes qui acceptent que chaque commit déclenche une release. release-please de Google fonctionne similairement à Changesets via des PR de release maintenues, avec une intégration GitHub Actions native. lerna-lite est une version allégée du célèbre Lerna, encore active et compatible monorepo. Pour 2026, Changesets reste le choix par défaut pour la majorité des cas grâce à son écosystème, sa documentation, et sa maturité.

Cas pratique : capitaliser les helpers UEMOA

Concrétisons avec un scénario réel. Un freelance de Dakar maintient un package @nomvotre/uemoa-helpers qui contient validations de téléphones, formatage FCFA, codes pays UEMOA, et formats de pièces d’identité (CNI, passeport, permis). Au début, il livre ce package directement aux trois clients qui l’utilisent en copiant les fichiers. Au bout de six mois, les divergences accumulées entre clients (chacun a ajouté ses petites adaptations) deviennent un cauchemar de maintenance. Migration vers un dépôt monorepo Bun, configuration Changesets, publication sur npm public sous une organisation à son nom. Désormais, chaque client consomme la même version stable, les corrections de bug profitent à tous, et le freelance gagne en réputation auprès de la communauté technique francophone qui découvre ses outils.

L’investissement initial — quelques jours pour structurer le monorepo, configurer Changesets, publier la première version — se rentabilise en moins de deux mois. Les nouveaux projets démarrent en quelques minutes (npm install @nomvotre/uemoa-helpers) au lieu de plusieurs heures de copier-coller adapté. La maintenance long-terme devient triviale : une seule release impacte tous les clients automatiquement quand ils mettent à jour. Pour les freelances ouest-africains qui veulent transformer leur expertise en actif technique, ce pattern est aujourd’hui le plus accessible et le plus payant à moyen terme.