Three gates before your first npm publish: 2FA, provenance, and staged releases

Description and use

Publishing an npm package encounters three hidden gates: 2FA, provenance generation, and staged publishing. The author explains how to bypass each using CI and trusted publishing.

Problem

Publishing a new npm package can fail at multiple hidden gates, causing confusion and delays.

Outcome

The developer successfully published the plugin, enabled provenance, and understood staged publishing mechanics, reducing future publish failures.

Workflow

• 1. Run npm whoami to verify token validity.
• 2. If publishing a new name, use a direct publish token and run npm publish interactively.
• 3. For provenance, add "provenance": true in publishConfig and publish from CI with --provenance and permissions: id-token: write.
• 4. Configure trusted publisher with npm trust github my-package --file publish.yml --repo my-org/my-repo --allow-publish.
• 5. For staged releases, use a stage‑only token and run npm stage publish after the first direct publish.
• 6. After publishing, wait for propagation and verify with curl https://registry.npmjs.org/my-package/0.1.0.
• 7. Update dist‑tags if needed with npm dist-tag add [email protected] latest.

Evidence

The account had 2FA set up with a security key, not a TOTP app.

Source

Automatic provenance generation not supported for provider: null

Source

Cannot publish "my-package": this token can only publish to a staging area, npm error and "my-package" does not exist yet.

Source