Create a new npm package without a live first release: staging and approval

Why does the package exist while its first release is not installable?

On October 2, 2026, GitHub announced that npm stage publish can create a new package without a manual first live release. This covers public scoped and unscoped packages, plus private scoped packages.

The npm documentation describes a 0.0.0-stage placeholder when a new package is staged. Before approval, the target version is not installable and its contents are not public. Approval releases that version for use under the package's access permissions. A visible placeholder does not prove that private contents are public, and approval must not be treated as changing the package's public or private settings.

Check versions, publishing access and 2FA first

Staging currently requires npm CLI 11.15.0 or later and Node 22.14.0 or later, publishing access to the package and an account with 2FA enabled. The npm 11.5.1 minimum in the trusted-publishing guide does not lower the higher requirement for staging.

Initial creation can use an authenticated local session or a granular access token with suitable permissions, including a stage-only token. The September 18 announcement says that token cannot run direct npm publish, even when configured to bypass 2FA for automation. The October 2 announcement adds creating new packages.

You do not need a prior live release, but an OIDC workflow without a configured trust relationship cannot be assumed to create any new package. The announcement's sequence is to create the package first, then manage its settings and configure trusted publishing. It gives no additional fee or regional guarantees outside that stated scope.

Step 1: submit the first release to staging

In the package's project root, confirm the package name and intended version in package.json. Retain your team's existing tests, build and review process, then run npm stage publish. This submits the content to staging; command success is not proof that the real release can be installed.

Keep the actual package name, intended version and stage-id so a maintainer can identify this submission. npm explicitly says that staging itself does not require a 2FA verification prompt. Account 2FA must still be enabled, and the later approval step still requires verification.

Step 2: inspect the actual content, then approve with 2FA

A maintainer can use npm stage list to find staged submissions they can access, then npm stage view followed by the target stage-id to inspect its details. To examine the actual tarball, use npm stage download followed by that stage-id. A package name or a successful CI badge alone does not prove the contents are correct.

Alternatively, find the submission in the Staged Packages tab on npmjs.com. Check its package name, version and contents, then run npm stage approve followed by the stage-id, or select Approve on the website. Both approval paths prompt for 2FA. Approval publishes that version to the package page.

For a hypothetical example, a team stages 1.0.0 for a new package. It sees 0.0.0-stage while 1.0.0 awaits review. A maintainer should inspect that same stage-id and decide whether to approve, rather than publish directly to rush it live. This illustrates the process, not the result of running a real package release.

Step 3: configure CI staging after the package exists

Once the package exists, configure its trusted publisher in the actual package settings, then let an authorized CI workflow run npm stage publish. OIDC authenticates the workflow with a short-lived identity credential. It enables later staging submissions, not bypassing initial configuration or maintainer approval.

Trusted publishing currently supports GitHub-hosted runners, GitLab.com shared runners and CircleCI cloud, but not self-hosted runners. This restriction applies to OIDC publishing authentication. It must not be expanded into a claim that every local-session or token-based staging flow forbids self-hosted environments.

OIDC supports npm stage publish, but npm stage list, view, approve and reject still require interactive authentication and proof of presence. Keep CI submission and maintainer review as two explicit stages. Obtaining an OIDC identity does not authorize unattended approval.

Staging access does not grant direct publishing or tag management

A granular stage-only token is not a read-only credential. The September 18 announcement explicitly says it retains write permissions such as moving dist-tags and deprecating versions, so protect it as a write credential. Blocking direct publication does not block every write action. These token permissions are distinct from an OIDC connection's Allowed actions.

In a trusted publisher's Allowed actions, direct npm publish and dist-tag management are separate permissions. Check what the actual connection permits. Do not enable unneeded direct publishing or tag access merely to make staging work; other connections do not change with it.

Check legacy rules as well. Configurations created before May 20, 2026 retain npm publish-only automatically. Those created before September 3, 2026 require at least one action to be selected explicitly. New configurations after September 3 automatically allow npm stage publish. This does not mean every historical connection gained staging access.

Keep submission, review and approval records separately. A queue entry, visible placeholder or successful OIDC authentication cannot replace a record that the target version was approved. Publishing access, account 2FA and your organization's existing approvals must each still be satisfied.