Staged publishing on npm adds an approval step: you or your CI run npm stage publish to submit a version to a staging area, and a maintainer then approves it with two-factor authentication before it goes live. It suits projects that want CI convenience with a human check.
The flow
- CI or a maintainer runs
npm stage publishin the package root. Staging itself does not need 2FA. - The staged version is not public. A maintainer reviews it.
- A maintainer approves it, in the CLI or on npmjs.com, and is prompted for 2FA.
- The version goes live.
You can stage from CI through trusted publishing, and a maintainer must still approve with 2FA. That is the main appeal. A compromised workflow can submit a package, but it cannot put it in front of users by itself.
Commands
| Task | Command |
|---|---|
| Submit a version | npm stage publish |
| List staged versions | npm stage list |
| Inspect one | npm stage view STAGE_ID |
| Download it to look at the files | npm stage download STAGE_ID |
| Approve and publish | npm stage approve STAGE_ID |
On npmjs.com the review happens in the Staged Packages tab.
Requirements
The documentation lists publish access to the package, 2FA enabled on your account, npm CLI 11.15.0 or later and Node.js 22.14.0 or higher. Check the page before you roll it out, since npm features change.
A caveat for brand new packages
If you stage a package that does not exist yet, npm publishes a placeholder version named 0.0.0-stage. The placeholder is publicly visible, though the staged version and its contents are not until approval. Do not be surprised when the name appears on the registry before your first real release.
What to review before approving
Staging is only useful if the review is real. Download the staged files and check:
- The file list matches what you expect. A stray .env file or build output is the classic mistake. See check what you are about to publish.
- The version number and dist tag are right.
- The install scripts in package.json are unchanged unless you changed them on purpose. See which npm lifecycle scripts run when you install.
- The release came from a commit you recognize.
How it fits with the other controls
Staging does not replace trusted publishing or a required review on workflow changes. It sits behind them as a final check. Combine it with disallow tokens and CODEOWNERS on your workflows. If you are the only maintainer, you are the approver, which still helps: the approval needs your second factor, so a stolen CI identity is not enough.
When it is overkill
A tiny package released twice a year may not need it. A widely used library with automated releases probably does. If approvals pile up unread, the control degrades into a click, so keep release volume low enough that someone looks.
Safeguard can scan the dependencies that go into each release and gate pull requests; the free scan is at gold.safeguard.sh/scan.
Quick check
Does staging need 2FA?
No. Approval does. Staging alone does not require it.
Can trusted publishing stage a package?
Yes. The docs say you can stage from CI through OIDC, and a maintainer must still approve with 2FA.
Sources
Last reviewed: 19 October 2026.
