NPM Package Release

npm package release and publishing

npm OIDC Trusted Publishing cannot create the first version of a package that does not exist yet, and a trust relationship cannot be created for a package that does not exist. The first version therefore needs one deliberate, human-in-the-loop publication; every later version is owned by CI.

Distinguish the two scenarios before acting:

• Scenario A: First release (Bootstrap) — The package has never been published to npm (registry returns 404). Follow the full bootstrap procedure (manual initial publish, then configure npm trust).
• Scenario B: Subsequent releases (CI / Second+ release) — The package already exists on npm (latest version exists, trust is configured). Releases belong entirely to GitHub Actions CI via Changesets. Do not treat subsequent releases, version bumps, or CI retries as a first-release bootstrap.

Hard rules

• Never ask the user to paste an OTP code into chat, and never automate npm login, browser approval, or OTP entry. Interactive steps belong to the user's own terminal, where prompts and browsers are visible to them.
• Publish before configuring trust. npm trust github on an unpublished package fails with 404 Package not found — that error means ordering, not a missing name.
• In pnpm workspaces always publish with pnpm publish. It rewrites workspace:* dependencies to real versions; plain npm publish would ship an unresolvable manifest.
• Do not run recursive root-level publishes (pnpm -r publish). Publish one package from its directory.

Procedure

0. Preconditions

• The package name is on the repository's release allowlist (for pi-packages: scripts/publish-release.mjs), so CI can take over after handoff.
• Version/changeset coordination is decided: either a pending changeset will produce a version PR, or the manifest version is already the exact version intended for first publication. The registry-aware CI publisher skips versions equal to what is on npm, so publishing an exact version early is safe.

1. Check credentials before anything else

npm whoami

• Success: continue.
• E401: the stored token is dead. npm actively retires bypass-2FA tokens, so tokens die silently even days after login. Ask the user to run npm login themselves and confirm when done. Do not proceed on a dead token.

A dead token is also why a publish of a brand-new package can fail with PUT ... 404 Not Found: the registry masks authorization failures for nonexistent packages as 404 instead of 401/403. When you see 404 on PUT, check npm whoami first before suspecting the package name.

2. Check registry state and route scenario

curl -s https://registry.npmjs.org/<package-name>

• 404 / no versions: Scenario A (First release) — proceed with Steps 3, 4, 5.
• Package exists with versions: Scenario B (Subsequent release) — STOP.
  • Do NOT ask the user to manually publish from their terminal.
  • Do NOT run npm trust again (trust relationship is already active).
  • Normal flow: create a Changeset (pnpm changeset), commit, push to main, and merge the Changesets Version PR. CI publishes automatically via OIDC.
  • If CI fails during a subsequent release: inspect CI logs first before assuming manual intervention is needed. For example, if the version already succeeded in publishing in the changesets/action step, a subsequent retry step encountering 409 Conflict simply means the package is already published on the registry (an eventual consistency or idempotency artifact), not an authorization or bootstrap failure.

Scenario A: First release bootstrap procedure

3. User publishes the first version (interactive)

The user runs, from the package directory:

pnpm publish --access public

pnpm prompts Enter OTP: inline; they type their authenticator code. If the branch is not the configured publish branch, pnpm asks to continue — answering yes is expected on wip/release branches.

If the user must publish the exact version a changesets version PR produces, check out that PR's branch and publish from there, then merge it; the CI publisher compares local vs registry versions and skips what already exists.

4. Establish the trust relationship

Still the user's terminal:

npm trust github <package-name> --file <release-workflow>.yml \
  --repo <owner>/<repo> --allow-publish -y

For pi-packages: --file release.yml --repo FradSer/pi-packages. This prints an auth URL and waits ("Press ENTER to open in the browser..."); the user approves in their browser. Requires npm >= 11.5.

If this fails with Package not found, step 3 has not actually completed — verify the registry before retrying.

5. Hand off to CI

Merge the feature/version PR. The release workflow's registry-aware publisher sees the published version and skips it; all subsequent versions publish via GitHub Actions OIDC with provenance — no local token involved ever again.

6. Verify

curl -s https://registry.npmjs.org/<package-name> | jq '."dist-tags".latest'

Registry edge caches can lag briefly after publish.

Failure quick table

Related project memory

• project_pi_package_npm_publishing — allowlist + version-PR coordination.
• github-ci-npm-publishing (pi-git-agent) — CI-only releases, npm trust CLI.
• npm-trusted-publishing (apple-events) — trust requires existing package.