Staged publishing adds an approval step before packages go live on the npm registry. Instead of publishing directly with npm publish, you can submit packages to a staging area with npm stage publish. A maintainer must then review and explicitly approve the staged package — with two-factor authentication (2FA) via the CLI or npmjs.com — before it becomes publicly available.

Staged publishing is useful when you want an extra review step before a package version becomes available on the registry.

You can use staged publishing for both new and existing packages. When you stage a package that does not yet exist, npm publishes a placeholder version of the package with the version 0.0.0-stage. This placeholder version is publicly available, but the staged version and its contents are not publicly available until a maintainer approves the staged package. After approval, the staged version is published to the package page.

How staged publishing works

Staged publishing has three steps:

1. Stage a package
2. Review a staged package
3. Approve a staged package

Prerequisites

Before using staged publishing, ensure the following:

• You have publish access to the package
• 2FA is enabled on your npm account

Stage a package

1. On the command line, navigate to the root directory of your package.

   cd /path/to/package

2. To stage your package, run:

   npm stage publish

   This submits your package to a staging area.

Review a staged package

After you stage a package, you can inspect it in the CLI or on npmjs.com.

Using the CLI

To list staged packages you have access to:

npm stage list [<package-spec>]

To view details for a specific staged package:

npm stage view <stage-id>

To download the staged package tarball for inspection:

npm stage download <stage-id>

Using npmjs.com

Open the Staged Packages tab to review staged packages and find the package you want to approve.

Approve a staged package

To publish a staged package to the registry, approve it with 2FA.

Using the CLI

To approve a staged package and publish it to the live registry:

npm stage approve <stage-id>

Using npmjs.com

On npmjs.com, review the staged package in the Staged Packages tab, then click Approve.

Approve or reject staged packages in batches

On npmjs.com, you can approve or reject multiple staged package versions with one confirmation and one 2FA challenge. Each batch applies the same action to every selected version.

Select package versions

1. Sign in to npmjs.com and open the Staged Packages tab in your account settings.
2. Review the package names, versions, dist-tags, publishers, and SHASUMs. Inspect or download the staged contents as needed before approving them.
3. Select Add to batch on each version you want to include. Use Filter by package or Load more to find versions.
4. Review the selected versions in the Batched section. Unselected versions appear under Available.

To remove a version from the batch, clear its In batch checkbox.

Confirm the batch action

1. Click Approve (N) or Reject (N), where N is the number of selected versions.
   • Approve publishes the selected versions to the registry.
   • Reject removes the selected staged versions without publishing them.
2. Review every package name and version in the confirmation dialog.
3. Click Approve packages or Reject packages to continue. Click Cancel to return without starting the batch.
4. Complete the 2FA challenge for the batch. You do not need a separate challenge for each version.

Monitor progress and handle failures

Keep the page open while the batch runs. The progress dialog shows a completion count and a status for each version:

• Waiting: The version has not started processing, or its result could not be confirmed. If a message appears, follow it before starting a new batch.
• Processing: The version is being approved or rejected.
• Succeeded: The version was published or removed successfully.
• Failed: The action failed. Review the message shown for that version.

When processing finishes, review the results and click Close to refresh the staged package list. Successfully published or rejected versions no longer appear in the list.

Try failed versions individually for more details. If the dialog reports an expired authorization or an unconfirmed result, refresh the page and check the current state before starting a new batch. If the dialog offers Retry because the results could not be finalized, click it to check completion again.

If a problem continues, contact npm Support with the package name and version.

Using staged publishing with trusted publishers

If you use trusted publishing (OIDC) from CI/CD, you can use staged publishing to submit a package for review before it goes live. A maintainer must still review and approve the staged package with 2FA.

For more information on configuring trusted publisher permissions, see "Trusted publishing for npm packages."

Learn more

• Trusted publishing for npm packages
• Generating provenance statements