Add recipe for publishing your first npm package with trusted publishing

[babblebey]

During the discussion in #6, @travi shared a detailed workflow for bootstrapping new npm packages when using trusted publishing. This is a real-world gap in our documentation, the "Initial release" sections in our release-workflow recipes assume a frictionless first publish that doesn't reflect current npm constraints.

The problem

npm's trusted publishing doesn't support publishing the first version of a package. You must publish an initial version with a granular access token, configure trusted publishing in the npm web UI, and only then does the normal CI-based flow work. Our docs currently skip this step entirely.

Where to add it

All three release-workflow recipes already have an "Initial release" section:

• Publishing on distribution channels - "Initial release"
• Publishing pre-releases - "Initial release"
• Publishing maintenance releases - "Initial release"

These sections currently describe an idealized feat: initial commit → v1.0.0 flow. They're the natural place to add a callout or subsection covering the trusted-publishing bootstrap, since that's the exact moment users will encounter the constraint.

What to add

A concise addition to the "Initial release" sections covering:

• The constraint: npm trusted publishing requires at least one version published via a granular access token before it can be enabled
• The workaround: Using npx semantic-release --no-ci locally for the initial publish
• Security best practices: Short-lived tokens, minimal scope, prompt revocation
• The transition: Configure trusted publishing in npm settings after first publish, then all subsequent releases go through CI normally

This can be a shared callout/admonition component or a consistent paragraph added to each section or a new recipe page, likely added under Recipes > Release Workflow; and linked to these sections.

the reference workflow (from #6)

1. Scaffold out a new package repo
2. Push main to the remote on GitHub
3. Create an alpha branch for initial pre-releases before promoting to stable v1.0.0
4. Push the alpha branch to the remote on GitHub
5. Create a new granular access token (as short-lived and narrow-scoped as possible)
6. Add that token to local user config (~/.npmrc)
7. Run npx semantic-release --no-ci locally
8. Visit npmjs.com for the new package
9. Configure trusted publishing in settings
10. Revoke the token
11. Continue pushing commits to alpha until ready for v1.0.0, confirming semantic-release works in CI
12. Merge alpha to main to promote to stable

Additional touchpoints

• The "Running semantic-release" page (from Proposal Rename "Installation" page to better reflect its actual content #6) should mention --no-ci briefly with a link to the relevant recipe section
• The pre-releases recipe is also an opportunity to more explicitly recommend using a pre-release branch (like alpha) to validate the pipeline before promoting to stable

Open questions

1. Should the trusted-publishing guidance be identical across all three recipe files, or tailored to each workflow? (The pre-releases recipe is the most natural fit for the full workflow since it already covers alpha/beta branches.)
2. Should we use a Starlight admonition/callout component to visually distinguish this as a platform-specific consideration?
3. Should we also cover other registries (GitHub Packages, etc.) or keep it npm-focused for now?
4. Is the alpha pre-release branch approach something we want to recommend as a general best practice for all new packages, or present as one option among several?
5. Any extra thoughts?

[travi]

2. Should we use a Starlight admonition/callout component to visually distinguish this as a platform-specific consideration?

if we add to the general initial flow docs, i think something like this would be valuable. this is unique to npm packages published specifically to the npm registry. the general flow docs dont necessarily refer even to npm, but could be for any type of asset. npm is our most common case, though.

3. Should we also cover other registries (GitHub Packages, etc.) or keep it npm-focused for now?

the existence of trusted publishing is only for the official npm registry, so i dont think we'd want to suggest an alternative publishing path for initial publish outside of that context. for example, with artifactory, even the initial publish of a new package can happen through OIDC

4. Is the alpha pre-release branch approach something we want to recommend as a general best practice for all new packages, or present as one option among several?

i do think think this is worthy of calling out more visibly as a recommended step when getting started. when the official npm registry is not involved, the initial publish complication would not be involved, but a pre-release is an opportunity to both make sure that the automation around releasing is all wired up correctly before attempting and possibly failing to publish a v1.0.0 as well as to organize initial functionality so that v1.0.0 can have useful functionality. similarly to our discouragement of gitflow, we should make it clear that this recommendation to start with a pre-release should be very short-lived with the goal of getting to v1.0.0 quickly with minimal functionality

this is possibly a good opportunity to highlight the default behavior of semantic-release to publish v1.0.0 as the first version. this can be a surprise to some that are used to starting at something like v0.0.1 and avoiding promotion to v1.0.0 until the project is quite mature. we discourage waiting until a project is mature to get to v1.0.0 and suggest publishing a minimal useful version as that so semver can communicate changes from that point most clearly. we touch on this elsewhere in the docs, but i think it is worth considering how those messages tie together.