Tout ce qui a bloqué lors de la publication de @hsblabs/web-stream-extras sur npm

Quand npm publish a passé, c’était une belle sensation.

Les problèmes sont venus après. Dès que j’ai migré vers GitHub Actions, trois choses ont cassé. La configuration du Trusted Publisher, les métadonnées liées à la provenance, et l’ordre des tags et versions—chacun a échoué pour une raison différente, à un endroit différent.

J’écris ça pour que la prochaine personne n’y perde pas le même temps.

Pourquoi publier ce paquet

@hsblabs/web-stream-extras est un petit paquet de helpers autour de la Web Streams API. Écrit initialement pour un usage interne, j’ai jugé qu’il était assez générique pour en faire un projet open source.

Pourquoi j’ai publié 0.0.1 manuellement en local

Pour la première version, j’ai lancé npm publish en local avant de configurer Actions. L’objectif était de vérifier que l’installation et l’import fonctionnent une fois le paquet sur npm. J’ai laissé l’infrastructure de release pour plus tard—automatiser avant que les choses soient stables ne fait qu’ajouter une couche de débogage.

Il y a une autre raison. Pour configurer le Trusted Publisher côté npmjs, le paquet doit déjà exister sur npm. Autrement dit, la toute première publication doit se faire d’une autre manière. Sans ça, on n’accède même pas à la page de paramétrage.

Migration vers GitHub Actions + Trusted Publisher pour 0.1.0

La publication manuelle s’est limitée à une seule fois, et tout ce qui a suivi est passé par GitHub Actions.

Le Trusted Publisher de npm permet de publier via OIDC sans émettre ni gérer de token. Il utilise un token à courte durée de vie généré par le workflow, ce qui évite de stocker NPM_TOKEN comme secret.

La configuration repose sur deux points. Côté npm, on précise le nom du fichier workflow lors de l’ajout d’un Trusted Publisher. Côté GitHub Actions, on ajoute la permission id-token: write et on supprime NODE_AUTH_TOKEN.

permissions:
  id-token: write
  contents: read

Laisser NODE_AUTH_TOKEN en place peut faire échouer le flux OIDC du Trusted Publisher. Si des instructions basées sur un token traînent encore dans le README ou les TODO, elles sèmeront la confusion—mieux vaut tout nettoyer lors de la migration.

Les erreurs réellement rencontrées

La publication bloque sur 422 Unprocessable Entity

Seule l’étape de publication dans Actions échouait. L’erreur était 422 Unprocessable Entity. Tout le reste passait, donc au début je n’avais aucune idée d’où chercher.

La cause : repository.url était vide dans package.json. Quand la provenance est activée, npm utilise repository.url pour relier le paquet à son dépôt. Si ce champ est absent, on obtient un 422.

// avant
"repository": {}

// après
"repository": {
  "type": "git",
  "url": "https://github.com/hsblabs/web-stream-extras"
}

Même en ayant vérifié toutes les autres métadonnées, ce champ passe facilement entre les mailles.

L’ordre du tag et de package.json.version

Le workflow vérifie que le nom du tag correspond à package.json.version.

Si on pousse le tag avant de mettre à jour la version, la vérification échoue. L’ordre correct :

1. Mettre à jour package.json.version et committer
2. Tagger ce commit
3. Pousser

Si l’ordre est inversé, la version dans le commit pointé par le tag ne correspond pas au nom du tag. En cas d’échec, supprimer le tag et le recréer.

git tag -d v0.1.0
git push origin :refs/tags/v0.1.0
# après le commit de mise à jour de version
git tag v0.1.0
git push origin v0.1.0

Le flux de release qui a fini par se stabiliser

Voici comment ça fonctionne maintenant :

1. Implémenter et tester
2. Mettre à jour package.json.version et committer
3. Pousser un tag v{version}
4. Actions détecte le push du tag et lance la publication

La validation avant publication est regroupée dans une commande publish:check—lint et vérifications de types sans --write. Placer cette étape avant la publication empêche des modifications non committées de s’y glisser. Enchaîner directement des commandes d’auto-correction peut créer des modifications non committées juste avant la publication, ce qui vaut la peine d’avoir en tête.

J’ai aussi lancé pnpm pack --dry-run pour inspecter le contenu du tarball. Même en limitant files à dist/, les sourcemaps peuvent s’y retrouver. Pour ne pas les publier, mieux vaut les exclure côté build.

Ce que je veux améliorer ensuite

Je veux intégrer la génération automatique du changelog dans le flux. Pour l’instant c’est manuel, et quelque chose échappe à chaque fois que je pousse un tag.

Les étapes pour passer d’une publication manuelle à Actions sont simples. Les difficultés viennent des détails de configuration. Le Trusted Publisher supprime la gestion des tokens, mais exige que les paramètres OIDC soient alignés avec précision. Vérifier que le côté npm et le côté Actions se correspondent point par point avant de lancer quoi que ce soit est le chemin le plus rapide.