Publiceren van npm packages

Het publiceren van NL Design System packages gaat (uitsluitend) automatisch via GitHub Actions pipelines. We volgen hierbij de Changesets-workflow, waarover je hier meer over het gebruik kunt lezen.

Op deze pagina lees je meer over de technische infrastructuur:

Hoe GitHub Actions is ingericht om publiceren mogelijk te maken.
Hoe publiceren met OpenID Connect werkt.
Waarom de eerste publicatie van een nieuw package anders is.
Wat je kunt controleren bij veelvoorkomende fouten.

GitHub Actions inrichten met de Changesets action

De relevante regels in de GitHub Actions workflow zijn als volgt:

publish-npm:
  environment:
    name: publish

  permissions:
    contents: read
    id-token: write

  steps:
    - name: Publish to npm Registry
      uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1.7.0
      id: changeset
      env:
        GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
        GIT_AUTHOR_EMAIL: ${{ secrets.GIT_AUTHOR_EMAIL }}
        GIT_AUTHOR_NAME: "NL Design System"
        GIT_COMMITTER_EMAIL: ${{ secrets.GIT_COMMITTER_EMAIL }}
        GIT_COMMITTER_NAME: "NL Design System"
        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Goed om te weten:

De job die een publish uitvoert, heeft veelal meer rechten nodig dan andere jobs. Om dit zo goed mogelijk te beveiligen, scopen we deze job in een aparte GitHub environment die we publish noemen. Zo zorgen we ervoor dat tokens alleen in deze job gebruikt kunnen worden en nergens anders.
Via env wordt GITHUB_TOKEN overschreven (met secrets.GH_TOKEN). Deze token wordt apart beschikbaar gesteld in de publish environment. De reden dat dit token wordt gebruikt (en niet de conventionele secrets.GITHUB_TOKEN) is dat de action een andere PR opent/updatet, en GitHub anders geen automatische checks start als ingebouwde beveiliging tegen infinite loops.
Onder permissions worden de rechten van GITHUB_TOKEN ingesteld. Omdat GH_TOKEN wordt gebruikt is contents: read voldoende. id-token: write is nodig voor OpenID Connect, waarover je hieronder meer leest.

Publiceren via OpenID Connect

Nieuwe versies van bestaande packages publiceren

We gebruiken OpenID Connect om packages te publiceren. Daarmee wordt bij een release veilig en automatisch een eenmalig token tussen GitHub Actions en de npm Registry uitgewisseld. Zo kan npm publiceren zonder een vast npm-token te hoeven mee te geven.

Dit heeft als voordeel dat:

Er geen handmatig beheerde publishing tokens nodig zijn.
Gelekte secrets minder risico opleveren, omdat er geen vast token is.
Publicaties aantoonbaar uit de juiste repository en workflow komen.

Nieuwe packages publiceren

Een beperking is dat OpenID Connect alleen werkt voor packages die al gepubliceerd zijn. De eerste publicatie van een nieuw package wordt dus nog wel met een npm token gedaan. Een kernteam admin kan jou helpen om deze in te stellen. Na die eerste publicatie kun je OpenID Connect gebruiken voor alle volgende versies.

Stappen in het kort:

Vraag een kernteam admin om de npm token in te stellen.
Merge de changesets publish PR die de nieuwe package zal publiceren.
De kernteam admin configureert trusted publishing via OpenID Connect in npmjs.org.
Publiceer vervolgversies via de normale GitHub Actions release pipeline.

Veelvoorkomende vragen

Soms lukt het publiceren van een package niet. De foutmelding die je in de GitHub Actions pipeline krijgt wijst vaak niet direct de oorzaak aan.

Ik krijg `E404 Not Found` tijdens publiceren

Controleer in deze volgorde:

Bestaat het package al op npmjs.com?
Is Trusted publishing correct ingesteld (repository, workflow-pad, environment)?
Komt het workflow-pad exact overeen, inclusief bestandsnaam en extensie (bijvoorbeeld: yaml vs. yml)?
Heeft de workflow de id-token: write permission?
Draait de release op Node.js 24 met een recente npm-versie?

Als het package nog nooit is gepubliceerd, voer dan eerst een eenmalige publicatie uit met een npm token.

Ik krijg een `E403 Forbidden` tijdens publiceren

Controleer in deze volgorde:

Betreft het een private package? Controleer dat de er een (read-only) npm-token is ingesteld zodat de huidige versie kan worden uitgelezen tijdens het publiceren.
Is de package niet al gepubliceerd? Soms zie je de nieuwste versie nog niet door cache.
Is de package unpublished? Versienummers kunnen dan niet worden hergebruikt. npm view <package> time om alle versies (inclusief unpublished) te zien.

Ik krijg een melding over een verlopen npm token

Bij OpenID Connect is een npm token niet nodig voor reguliere releases. Zo’n foutmelding betekent vaak dat de workflow nog niet volledig via Trusted publishing publiceert. Controleer dan opnieuw de OIDC-instellingen in npm en de workflow permissions.