docs: clarify staged publishing can create new packages (#2047) · npm/documentation@dd84163 · GitHub
Skip to content

Commit dd84163

Browse files
shmamCopilotkarenjli
authored
docs: clarify staged publishing can create new packages (#2047)
## Summary Clarifies that staged publishing can soon be used to **create brand-new packages**, not just stage new versions of packages that already exist on the registry. ## Changes - `content/packages-and-modules/securing-your-code/staged-publishing.mdx` — updated the Prerequisites bullet to reflect that a package can be brand-new or already published. ## Companion PR The `npm stage` CLI reference pages (`content/cli/v11` and `v12`) carry the same "Package must exist" prerequisite, but those files are auto-generated from the [`npm/cli`](https://github.com/npm/cli) repo (`docs/lib/content/commands/npm-stage.md`) via the `update-cli` workflow. The matching fix is in npm/cli#10017 so the correction isn't overwritten on the next sync. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Karen Li <karenjli@github.com> Co-authored-by: Karen Li <47998177+karenjli@users.noreply.github.com>
1 parent d1cbe2e commit dd84163

8 files changed

Lines changed: 107 additions & 86 deletions

File tree

‎cli-cache.json‎

Lines changed: 1 addition & 1 deletion

‎content/cli/v11/commands/npm-stage.mdx‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Key behaviors:
3939

4040
- Staged packages share the same semver version unique index as published packages — you cannot publish a version that already exists as a staged version for that package.
4141
- You can still publish packages normally while you have staged packages pending.
42+
- Staged publishing will allow you to create a new package if it does not exist.
4243
- You can stage multiple versions of the same package.
4344
- `npm stage publish` has parity with `npm publish` and will respect `"private": true` in `package.json`, refusing to stage the package.
4445

@@ -47,7 +48,6 @@ Key behaviors:
4748
Before using `npm stage` commands, ensure the following requirements are met:
4849

4950
- **Write permissions on the package:** You must have write access to the package you're configuring.
50-
- **Package must exist:** The package you're configuring must already exist on the npm registry.
5151
- **2FA enabled on your account:** Commands that require 2FA will prompt you to authenticate. If you don't already have 2FA enabled on your account, you must enable it before using these commands.
5252

5353
### Subcommands
@@ -61,14 +61,14 @@ Before using `npm stage` commands, ensure the following requirements are met:
6161

6262
### 2FA Requirements by Subcommand
6363

64-
| Command | Requires 2FA | Notes |
65-
| --- | --- | --- |
66-
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
67-
| `npm stage list` | No | View staged packages |
68-
| `npm stage view` | No | View staged package details |
69-
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
70-
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
71-
| `npm stage download` | No | Downloads the tarball for local inspection |
64+
| Command | Requires 2FA | Notes |
65+
| -------------------- | ------------ | -------------------------------------------------------- |
66+
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
67+
| `npm stage list` | No | View staged packages |
68+
| `npm stage view` | No | View staged package details |
69+
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
70+
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
71+
| `npm stage download` | No | Downloads the tarball for local inspection |
7272

7373
### Tag Behavior
7474

@@ -80,12 +80,12 @@ The tag is an immutable property of the staged package. Once a package is staged
8080

8181
The key difference with staged publishing is that `npm stage publish` never requires a 2FA prompt, regardless of token type. This is what makes it suitable for automated workflows. The goal of `npm stage publish` is deferring proof-of-presence to a later point in time.
8282

83-
| Token Type | `npm stage publish` | `npm publish` |
84-
| --- | --- | --- |
85-
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
86-
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
87-
| Session token | Can stage | 2FA prompt |
88-
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |
83+
| Token Type | `npm stage publish` | `npm publish` |
84+
| ------------------ | ---------------------- | ----------------------------------------------------- |
85+
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
86+
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
87+
| Session token | Can stage | 2FA prompt |
88+
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |
8989

9090
### Trust Relationship Permissions
9191

‎content/cli/v12/commands/npm-stage.mdx‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ Key behaviors:
5555

5656
- Staged packages share the same semver version unique index as published packages — you cannot publish a version that already exists as a staged version for that package.
5757
- You can still publish packages normally while you have staged packages pending.
58+
- Staged publishing will allow you to create a new package if it does not exist.
5859
- You can stage multiple versions of the same package.
5960
- `npm stage publish` has parity with `npm publish` and will respect `"private": true` in `package.json`, refusing to stage the package.
6061

@@ -63,7 +64,6 @@ Key behaviors:
6364
Before using `npm stage` commands, ensure the following requirements are met:
6465

6566
- **Write permissions on the package:** You must have write access to the package you're configuring.
66-
- **Package must exist:** The package you're configuring must already exist on the npm registry.
6767
- **2FA enabled on your account:** Commands that require 2FA will prompt you to authenticate. If you don't already have 2FA enabled on your account, you must enable it before using these commands.
6868

6969
### Subcommands
@@ -77,14 +77,14 @@ Before using `npm stage` commands, ensure the following requirements are met:
7777

7878
### 2FA Requirements by Subcommand
7979

80-
| Command | Requires 2FA | Notes |
81-
| --- | --- | --- |
82-
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
83-
| `npm stage list` | No | View staged packages |
84-
| `npm stage view` | No | View staged package details |
85-
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
86-
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
87-
| `npm stage download` | No | Downloads the tarball for local inspection |
80+
| Command | Requires 2FA | Notes |
81+
| -------------------- | ------------ | -------------------------------------------------------- |
82+
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
83+
| `npm stage list` | No | View staged packages |
84+
| `npm stage view` | No | View staged package details |
85+
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
86+
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
87+
| `npm stage download` | No | Downloads the tarball for local inspection |
8888

8989
### Tag Behavior
9090

@@ -96,12 +96,12 @@ The tag is an immutable property of the staged package. Once a package is staged
9696

9797
The key difference with staged publishing is that `npm stage publish` never requires a 2FA prompt, regardless of token type. This is what makes it suitable for automated workflows. The goal of `npm stage publish` is deferring proof-of-presence to a later point in time.
9898

99-
| Token Type | `npm stage publish` | `npm publish` |
100-
| --- | --- | --- |
101-
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
102-
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
103-
| Session token | Can stage | 2FA prompt |
104-
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |
99+
| Token Type | `npm stage publish` | `npm publish` |
100+
| ------------------ | ---------------------- | ----------------------------------------------------- |
101+
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
102+
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
103+
| Session token | Can stage | 2FA prompt |
104+
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |
105105

106106
### Trust Relationship Permissions
107107

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,8 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
117117

118118
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.
119119

120+
If the package does not yet exist, staging it publishes a placeholder version of the package that is publicly available. The staged version and its contents are not available until the staged package is approved.
121+
120122
A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
121123

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

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,8 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
119119

120120
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.
121121

122+
If the package does not yet exist, staging it publishes a placeholder version of the package that is publicly available. The staged version and its contents are not publicly available until the staged package is approved.
123+
122124
A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
123125

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

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,8 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
9898

9999
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.
100100

101+
If the package does not yet exist, staging it publishes a placeholder version of the package that is publicly available. The staged version and its contents are not publicly available until the staged package is approved.
102+
101103
A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
102104

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

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

Lines changed: 2 additions & 1 deletion

‎package-lock.json‎

Lines changed: 68 additions & 54 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)