patch-1
@reggi/path-to-regexp
dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2
dependabot/npm_and_yarn/main/eslint-10.4.0
dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0
dependabot/npm_and_yarn/main/proc-log-7.0.0
dependabot/npm_and_yarn/npm_and_yarn-826852524d
dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2
deprecate-totp-2fa
dhei/classic-tokens
gat-bypass-2fa-docs
jpg619/fix-accessibility-content-flow
jpg619/version-bump-tar-2
kartykp/gat-bypass-2fa-docs
kartykp/upgrade-path-to-regex
main
maitxn/version-bump-tar
patch-1
reggi/cache-based-on-version
reggi/dev-engines
reggi/fix-transform-prettier
reggi/overrides
update-search-sensitivity
| 1 | --- |
| 2 | title: Staged publishing for npm packages |
| 3 | --- |
| 4 | |
| 5 | 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](https://www.npmjs.com) — before it becomes publicly available. |
| 6 | |
| 7 | Staged publishing is useful when you want an extra review step before a package version becomes available on the registry. |
| 8 | |
| 9 | <Note> |
| 10 | |
| 11 | **Note:** Staged publishing requires [npm CLI](https://docs.npmjs.com/cli/v11) version 11.15.0 or later and Node version 22.14.0 or higher. |
| 12 | |
| 13 | </Note> |
| 14 | |
| 15 | ## How staged publishing works |
| 16 | |
| 17 | Staged publishing has three steps: |
| 18 | |
| 19 | 1. [Stage a package](#stage-a-package) |
| 20 | 2. [Review a staged package](#review-a-staged-package) |
| 21 | 3. [Approve a staged package](#approve-a-staged-package) |
| 22 | |
| 23 | ## Prerequisites |
| 24 | |
| 25 | Before using staged publishing, ensure the following: |
| 26 | |
| 27 | - You have **publish access** to the package |
| 28 | - The package **already exists** on the npm registry — you cannot stage a brand-new package |
| 29 | - **2FA is enabled** on your npm account |
| 30 | |
| 31 | ## Stage a package |
| 32 | |
| 33 | 1. On the command line, navigate to the root directory of your package. |
| 34 | |
| 35 | ``` |
| 36 | cd /path/to/package |
| 37 | ``` |
| 38 | |
| 39 | 2. To stage your package, run: |
| 40 | |
| 41 | ``` |
| 42 | npm stage publish |
| 43 | ``` |
| 44 | |
| 45 | This submits your package to a staging area. |
| 46 | |
| 47 | <Note> |
| 48 | |
| 49 | **Note:** `npm stage publish` does not require 2FA. |
| 50 | |
| 51 | </Note> |
| 52 | |
| 53 | ## Review a staged package |
| 54 | |
| 55 | After you stage a package, you can inspect it in the CLI or on [npmjs.com](https://www.npmjs.com). |
| 56 | |
| 57 | #### Using the CLI |
| 58 | |
| 59 | To list staged packages you have access to: |
| 60 | |
| 61 | ``` |
| 62 | npm stage list [<package-spec>] |
| 63 | ``` |
| 64 | |
| 65 | To view details for a specific staged package: |
| 66 | |
| 67 | ``` |
| 68 | npm stage view <stage-id> |
| 69 | ``` |
| 70 | |
| 71 | To download the staged package tarball for inspection: |
| 72 | |
| 73 | ``` |
| 74 | npm stage download <stage-id> |
| 75 | ``` |
| 76 | |
| 77 | #### Using npmjs.com |
| 78 | |
| 79 | Open the **Staged Packages** tab to review staged packages and find the package you want to approve. |
| 80 | |
| 81 | <Screenshot |
| 82 | src="/packages-and-modules/securing-your-code/staged-package-tab.png" |
| 83 | alt="Screenshot showing the Staged Packages tab on npmjs.com with staged packages ready for review" |
| 84 | /> |
| 85 | |
| 86 | ## Approve a staged package |
| 87 | |
| 88 | To publish a staged package to the registry, approve it with 2FA. |
| 89 | |
| 90 | #### Using the CLI |
| 91 | |
| 92 | To approve a staged package and publish it to the live registry: |
| 93 | |
| 94 | ``` |
| 95 | npm stage approve <stage-id> |
| 96 | ``` |
| 97 | |
| 98 | #### Using npmjs.com |
| 99 | |
| 100 | On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**. |
| 101 | |
| 102 | <Screenshot |
| 103 | src="/packages-and-modules/securing-your-code/staged-package-approve.png" |
| 104 | alt="Screenshot showing a staged package on npmjs.com with the Approve button" |
| 105 | /> |
| 106 | |
| 107 | <Note> |
| 108 | |
| 109 | **Note:** You will be prompted for 2FA verification whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). |
| 110 | |
| 111 | </Note> |
| 112 | |
| 113 | ## Using staged publishing with trusted publishers |
| 114 | |
| 115 | If you use [trusted publishing (OIDC)](/trusted-publishers) 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. |
| 116 | |
| 117 | For more information on configuring trusted publisher permissions, see "[Trusted publishing for npm packages](/trusted-publishers#configuring-allowed-actions)." |
| 118 | |
| 119 | ## Learn more |
| 120 | |
| 121 | - [Trusted publishing for npm packages](./trusted-publishers) |
| 122 | - [Generating provenance statements](./generating-provenance-statements) |