Support npm staged publishing in changeset publish #2025

Affected Packages

@changesets/cli
@changesets/action

Problem

npm recently added staged publishing via npm stage publish in npm CLI 11.15.0. This lets CI submit a package version to npm without making it public immediately. A maintainer can then review the staged package and explicitly approve it with 2FA before it goes live.

Today, changeset publish only supports immediate publishing through normal package-manager publishing. In a Changesets monorepo, teams who want npm staged publishing need custom scripting for package selection, publish dirs, access/tag handling, ignored/private packages, and post-approval tagging.

npm docs: https://docs.npmjs.com/staged-publishing/

Proposed Solution

Add first-class support for npm staged publishing.

Possible API:

changeset publish --stage

or:

changeset publish --publish-mode=stage

When enabled, Changesets would use npm stage publish instead of immediate publishing for packages that need publishing.

The staged mode should probably avoid creating git tags during the staging step, because a staged package is not live yet and may be rejected. A safe flow would be:

1. changeset version
2. build packages
3. changeset publish --stage
4. maintainer reviews staged packages with npm stage list, npm stage view, and/or npm stage download
5. maintainer approves staged packages with npm stage approve <stage-id>
6. run changeset tag or another finalize step after approval

Notes / Constraints

npm staged publishing has a few constraints that Changesets could account for or document:

• Requires npm CLI 11.15.0 or later.
• Requires Node 22.14.0 or later.
• npm stage is not workspace-aware.
• The package must already exist on the npm registry; brand-new packages cannot be staged.
• npm stage publish does not require 2FA, but npm stage approve does.
• The tag used during staging is immutable; changing it requires rejecting and staging again.