Add documentation for staged publishing

content/nav.yml

@@ -158,6 +158,8 @@
           url: /generating-provenance-statements
         - title: Trusted publishing with OIDC
           url: /trusted-publishers
+        - title: Staged publishing
+          url: /staged-publishing
         - title: About ECDSA registry signatures
           url: /about-registry-signatures
         - title: Verifying ECDSA registry signatures

content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-private-packages.mdx

@@ -81,16 +81,19 @@ npm install my-package
 
 By default, scoped packages are published with private visibility.
 
-<Note variant="warning">
+There are two ways to publish your package to the npm registry:
 
-**Important:** Publishing to npm requires either:
+1. [Direct publishing](#direct-publishing)
+2. [Staged publishing](#staged-publishing)
 
-- Two-factor authentication (2FA) enabled on your account, OR
-- A granular access token with bypass 2FA enabled
+### Direct publishing
 
-For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
+To publish directly with `npm publish`, you need either:
 
-</Note>
+- Two-factor authentication (2FA) enabled on your account, or
+- A granular access token (GAT) with bypass 2FA enabled
+
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
 
 1. On the command line, navigate to the root directory of your package.
 
@@ -110,6 +113,42 @@ For more information, see the npm documentation on [requiring 2FA for package pu
 
 For more information on the `publish` command, see the [CLI documentation][cli-publish].
 
+### Staged publishing
+
+Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package is published to the registry, a maintainer must review and approve it with 2FA.
+
+A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
+
+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.
+
+3. To check that your package has been staged, use either of the following methods:
+   - In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID.
+   - On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages.
+
+4. To approve and publish the staged package, use one of the following methods:
+   - In the CLI, run the `npm stage approve <stage-id>` command.
+   - On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
+
+   <Note>
+
+   **Note:** You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). Once approved, the package is published to the live registry.
+
+   </Note>
+
+For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing].
+
 [scopes]: about-scopes
 [private-pkgs]: about-private-packages
 [user-signup]: https://www.npmjs.com/signup
@@ -123,3 +162,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
 [config-2fa]: /configuring-two-factor-authentication
 [creating-token]: /creating-and-viewing-access-tokens
 [requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
+[staged-publishing]: /staged-publishing

content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-scoped-public-packages.mdx

@@ -77,16 +77,19 @@ npm install /path/to/my-test-package
 
 By default, scoped packages are published with private visibility. To publish a scoped package with public visibility, use `npm publish --access public`.
 
-<Note variant="warning">
+There are two ways to publish your package to the npm registry:
 
-**Important:** Publishing to npm requires either:
+1. [Direct publishing](#direct-publishing)
+2. [Staged publishing](#staged-publishing)
 
-- Two-factor authentication (2FA) enabled on your account, OR
-- A granular access token with bypass 2FA enabled
+### Direct publishing
 
-For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
+To publish directly with `npm publish --access public`, you need either:
 
-</Note>
+- Two-factor authentication (2FA) enabled on your account, or
+- A granular access token (GAT) with bypass 2FA enabled
+
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
 
 1. On the command line, navigate to the root directory of your package.
 
@@ -112,6 +115,42 @@ For more information, see the npm documentation on [requiring 2FA for package pu
 
 For more information on the `publish` command, see the [CLI documentation][cli-publish].
 
+### Staged publishing
+
+Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package becomes publicly available, a maintainer must review and approve it with 2FA.
+
+A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
+
+1. On the command line, navigate to the root directory of your package.
+
+   ```
+   cd /path/to/my-test-package
+   ```
+
+2. To stage your scoped public package, run:
+
+   ```
+   npm stage publish
+   ```
+
+   This submits your package to a staging area.
+
+3. To check that your package has been staged, use either of the following methods:
+   - In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID.
+   - On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages.
+
+4. To approve and publish the staged package, use one of the following methods:
+   - In the CLI, run the `npm stage approve <stage-id>` command.
+   - On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
+
+   <Note>
+
+   **Note:** You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). Once approved, the package is published to the live registry.
+
+   </Note>
+
+For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing].
+
 [scopes]: /about-scopes
 [user-signup]: https://www.npmjs.com/signup
 [create-org]: https://www.npmjs.com/signup?next=/org/create
@@ -125,3 +164,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
 [config-2fa]: /configuring-two-factor-authentication
 [creating-token]: /creating-and-viewing-access-tokens
 [requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
+[staged-publishing]: /staged-publishing

content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx

@@ -58,16 +58,19 @@ npm install path/to/my-package
 
 ## Publishing unscoped public packages
 
-<Note variant="warning">
+There are two ways to publish your package to the npm registry:
 
-**Important:** Publishing to npm requires either:
+1. [Direct publishing](#direct-publishing)
+2. [Staged publishing](#staged-publishing)
 
-- Two-factor authentication (2FA) enabled on your account, OR
-- A granular access token with bypass 2FA enabled
+### Direct publishing
 
-For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
+To publish directly with `npm publish`, you need either:
 
-</Note>
+- Two-factor authentication (2FA) enabled on your account, or
+- A granular access token (GAT) with bypass 2FA enabled
+
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
 
 1. On the command line, navigate to the root directory of your package.
 
@@ -91,6 +94,42 @@ For more information, see the npm documentation on [requiring 2FA for package pu
 
 For more information on the `publish` command, see the [CLI documentation][cli-publish].
 
+### Staged publishing
+
+Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package becomes publicly available, a maintainer must review and approve it with 2FA.
+
+A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
+
+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.
+
+3. To check that your package has been staged, use either of the following methods:
+   - In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID.
+   - On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages.
+
+4. To approve and publish the staged package, use one of the following methods:
+   - In the CLI, run the `npm stage approve <stage-id>` command.
+   - On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
+
+   <Note>
+
+   **Note:** You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). Once approved, the package is published to the live registry.
+
+   </Note>
+
+For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing].
+
 [pkg-viz]: package-scope-access-level-and-visibility
 [user-signup]: https://www.npmjs.com/signup
 [create-org]: https://www.npmjs.com/signup?next=/org/create
@@ -103,3 +142,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
 [config-2fa]: /configuring-two-factor-authentication
 [creating-token]: /creating-and-viewing-access-tokens
 [requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
+[staged-publishing]: /staged-publishing

content/packages-and-modules/securing-your-code/staged-publishing.mdx

@@ -0,0 +1,122 @@
+---
+title: Staged publishing for npm packages
+---
+
+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.
+
+Staged publishing is useful when you want an extra review step before a package version becomes available on the registry.
+
+<Note>
+
+**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.
+
+</Note>
+
+## How staged publishing works
+
+Staged publishing has three steps:
+
+1. [Stage a package](#stage-a-package)
+2. [Review a staged package](#review-a-staged-package)
+3. [Approve a staged package](#approve-a-staged-package)
+
+## Prerequisites
+
+Before using staged publishing, ensure the following:
+
+- You have **publish access** to the package
+- The package **already exists** on the npm registry — you cannot stage a brand-new 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.
+
+<Note>
+
+**Note:** `npm stage publish` does not require 2FA.
+
+</Note>
+
+## Review a staged package
+
+After you stage a package, you can inspect it in the CLI or on [npmjs.com](https://www.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.
+
+<Screenshot
+   src="/packages-and-modules/securing-your-code/staged-package-tab.png"
+   alt="Screenshot showing the Staged Packages tab on npmjs.com with staged packages ready for review"
+/>
+
+## 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](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
+
+<Screenshot
+   src="/packages-and-modules/securing-your-code/staged-package-approve.png"
+   alt="Screenshot showing a staged package on npmjs.com with the Approve button"
+/>
+
+<Note>
+
+**Note:** You will be prompted for 2FA verification whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com).
+
+</Note>
+
+## Using staged publishing with trusted publishers
+
+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.
+
+For more information on configuring trusted publisher permissions, see "[Trusted publishing for npm packages](/trusted-publishers#configuring-allowed-actions)."
+
+## Learn more
+
+- [Trusted publishing for npm packages](./trusted-publishers)
+- [Generating provenance statements](./generating-provenance-statements)