vite-plus 1.5.0 → 1.6.0

package/docs/guide/package-management/package-manager-selection.md

@@ -0,0 +1,60 @@
+# Package Manager Selection
+
+`vp` detects the package manager at the workspace root in this order:
+
+1. `packageManager` in `package.json`
+2. `devEngines.packageManager` in `package.json`
+3. `pnpm-workspace.yaml`
+4. `pnpm-lock.yaml`
+5. `yarn.lock` or `.yarnrc.yml`
+6. `package-lock.json`
+7. `bun.lock` or `bun.lockb`
+8. `.pnpmfile.cjs` or `pnpmfile.cjs`
+9. `bunfig.toml`
+10. `yarn.config.cjs`
+
+If none of these declarations or files is present, Vite+ defaults to pnpm. Vite+ downloads the matching package manager as needed. Detection does not rewrite `package.json`.
+
+Yarn Classic is Yarn 1. Yarn Modern is Yarn 2 or later.
+
+## Pinning a Version
+
+Use [`vp env pin`](/guide/env) to declare an exact package-manager version:
+
+```bash
+vp env pin pnpm@11.3.0
+```
+
+A `packageManager` pin can include an integrity hash, such as `yarn@4.17.1+sha512.…`. Vite+ supports Corepack-compatible integrity hashes and stops if verification fails.
+
+## Version Ranges
+
+The [`devEngines.packageManager`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines) field accepts an object or an array of objects. Its `version` can be a semver range:
+
+```json
+{
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "^11.0.0",
+      "onFail": "download"
+    }
+  }
+}
+```
+
+Vite+ uses an already-downloaded satisfying version when possible. Otherwise, it resolves the latest satisfying version from the npm registry. The range remains the source of truth and is not replaced with an exact `packageManager` pin.
+
+When both fields are present, `packageManager` drives selection. Vite+ warns if it does not satisfy the `devEngines.packageManager` constraint. Run `vp env doctor` for details.
+
+## Package-Manager Shims
+
+An explicit `packageManager` or `devEngines.packageManager` declaration also controls matching package-manager shims. For example, `packageManager: "npm@10.9.4"` makes `npm` and `npx` use npm 10.9.4.
+
+The same applies to the generated aliases for each manager:
+
+- pnpm: `pnpm`, `pnpx`, `pn`, and `pnx`.
+- Yarn: `yarn` and `yarnpkg`.
+- Bun: `bun` and `bunx`.
+
+Mismatched tools are not translated. Running `npm` in a pnpm project still resolves npm. Use `vp` package-management commands when you want Vite+ to adapt the operation to the project's manager.

package/docs/guide/package-management/patch-commit.md

@@ -0,0 +1,27 @@
+# vp pm patch-commit
+
+Save edits prepared with [patch](./patch) as a dependency patch.
+
+```bash
+vp pm patch-commit /path/to/edited-package
+```
+
+## Options
+
+Supply the edit directory from the manager's patch workflow. There are no additional Vite+ options.
+
+There are no command-specific options.
+
+## Compatibility
+
+- **npm:** 12 or later: `npm patch commit`. Earlier versions warn and skip.
+- **pnpm:** 7.4 or later: `pnpm patch-commit`. Earlier versions warn and skip.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** 3 or later: `yarn patch-commit --save`. Earlier versions warn and skip.
+- **Bun:** `bun patch --commit`.
+
+Review and commit the patch and any manifest or lockfile changes produced by the manager.
+
+## Native Options
+
+For native options, see [npm patch commit](https://docs.npmjs.com/cli/v12/commands/npm-patch), [pnpm patch-commit](https://pnpm.io/cli/patch-commit), [Yarn patch-commit](https://yarnpkg.com/cli/patch-commit), and [Bun patch --commit](https://bun.com/docs/pm/cli/patch). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/patch.md

@@ -0,0 +1,29 @@
+# vp pm patch
+
+Prepare an installed dependency for local patching.
+
+```bash
+vp pm patch my-dependency@1.0.0
+```
+
+Edit the package in the location reported by the native manager, then save the patch with [patch-commit](./patch-commit).
+
+## Options
+
+A package specification is required. There are no additional Vite+ options.
+
+There are no command-specific options.
+
+## Compatibility
+
+- **npm:** 12 or later: `npm patch add`. Earlier versions warn and skip.
+- **pnpm:** 7.4 or later: `pnpm patch`. Earlier versions warn and skip.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** `yarn patch`.
+- **Bun:** `bun patch`.
+
+The edit location and patch storage format are native-manager details. Vite+ does not convert patches between managers.
+
+## Native Options
+
+For native options, see [npm patch add](https://docs.npmjs.com/cli/v12/commands/npm-patch), [pnpm patch](https://pnpm.io/cli/patch), [Yarn patch](https://yarnpkg.com/cli/patch), and [Bun patch](https://bun.com/docs/pm/cli/patch). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/ping.md

@@ -0,0 +1,32 @@
+# vp pm ping
+
+Check connectivity to a package registry.
+
+```bash
+vp pm ping
+vp pm ping --registry https://registry.npmjs.org
+```
+
+## Options
+
+| Option             | Description          | Notes |
+| ------------------ | -------------------- | ----- |
+| `--registry <url>` | Select the registry. |       |
+
+## Compatibility
+
+- **npm:** `npm ping`.
+- **pnpm:** 11 or later: `pnpm ping`. Earlier versions use `npm ping` as a fallback.
+- **Yarn Classic:** Fallback: `npm ping`.
+- **Yarn Modern:** Fallback: `npm ping`.
+- **Bun:** Fallback: `npm ping`.
+
+| Option             | npm | pnpm | Yarn Classic | Yarn Modern | Bun | Notes |
+| ------------------ | --- | ---- | ------------ | ----------- | --- | ----- |
+| `--registry <url>` | Yes | Yes  | Yes          | Yes         | Yes |       |
+
+Registry configuration, output, and exit codes follow the command that runs. Use [whoami](./whoami) when you need to check the authenticated account rather than connectivity.
+
+## Native Options
+
+For native options, see [npm ping](https://docs.npmjs.com/cli/v11/commands/npm-ping) and [pnpm ping](https://pnpm.io/cli/ping). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/pkg.md

@@ -0,0 +1,88 @@
+# vp pm pkg
+
+Read and update `package.json` fields without editing the manifest by hand.
+
+```bash
+vp pm pkg get name version
+vp pm pkg set scripts.check='vp check'
+vp pm pkg set private=true --json
+vp pm pkg delete scripts.old
+vp pm pkg fix
+```
+
+## Options
+
+- `get [key...]` reads fields, or the entire manifest if no keys are supplied. `--json` requests native JSON output.
+- `set <key=value...>` writes fields. `--json` parses values as JSON so booleans, numbers, arrays, and objects are not saved as strings.
+- `delete <key...>` removes fields.
+- `fix` asks the manager to correct common manifest errors.
+
+Field paths and normalization follow the native manager. Quote paths with brackets or shell-sensitive characters.
+
+### `get`
+
+| Option   | Description            | Notes                             |
+| -------- | ---------------------- | --------------------------------- |
+| `--json` | Output in JSON format. | Output retains the native schema. |
+
+### `set`
+
+| Option   | Description                          | Notes                                                                     |
+| -------- | ------------------------------------ | ------------------------------------------------------------------------- |
+| `--json` | Parse values as JSON before writing. | Parses booleans, numbers, arrays, and objects rather than saving strings. |
+
+### `delete`
+
+There are no command-specific options.
+
+### `fix`
+
+There are no command-specific options.
+
+## Compatibility
+
+### `get`
+
+- **npm:** 7.20.0 or later: `npm pkg get`. Earlier versions warn and skip.
+- **pnpm:** 11.3.0 or later: `pnpm pkg get`. Earlier versions warn and skip.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** No command. Warns and exits successfully without performing the operation.
+- **Bun:** 1.2.19 or later: `bun pm pkg get`. Earlier versions warn and skip.
+
+| Option   | npm             | pnpm            | Yarn Classic | Yarn Modern | Bun             | Notes |
+| -------- | --------------- | --------------- | ------------ | ----------- | --------------- | ----- |
+| `--json` | 7.20.0 or later | 11.3.0 or later | No           | No          | 1.2.19 or later |       |
+
+### `set`
+
+- **npm:** 7.20.0 or later: `npm pkg set`. Earlier versions warn and skip.
+- **pnpm:** 11.3.0 or later: `pnpm pkg set`. Earlier versions warn and skip.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** No command. Warns and exits successfully without performing the operation.
+- **Bun:** 1.2.19 or later: `bun pm pkg set`. Earlier versions warn and skip.
+
+| Option   | npm             | pnpm            | Yarn Classic | Yarn Modern | Bun             | Notes |
+| -------- | --------------- | --------------- | ------------ | ----------- | --------------- | ----- |
+| `--json` | 7.20.0 or later | 11.3.0 or later | No           | No          | 1.2.19 or later |       |
+
+### `delete`
+
+- **npm:** 7.20.0 or later: `npm pkg delete`. Earlier versions warn and skip.
+- **pnpm:** 11.3.0 or later: `pnpm pkg delete`. Earlier versions warn and skip.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** No command. Warns and exits successfully without performing the operation.
+- **Bun:** 1.2.19 or later: `bun pm pkg delete`. Earlier versions warn and skip.
+
+### `fix`
+
+- **npm:** 9.8.0 or later: `npm pkg fix`. Earlier versions warn and skip.
+- **pnpm:** 11.3.0 or later: `pnpm pkg fix`. Earlier versions warn and skip.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** No command. Warns and exits successfully without performing the operation.
+- **Bun:** 1.2.19 or later: `bun pm pkg fix`. Earlier versions warn and skip.
+
+Versions below the stated requirements warn and exit successfully without running the operation. There is no npm fallback for unsupported managers or versions.
+
+## Native Options
+
+For native options, see [npm pkg](https://docs.npmjs.com/cli/v11/commands/npm-pkg), [pnpm pkg](https://pnpm.io/cli/pkg), and [Bun pm pkg](https://bun.com/docs/pm/cli/pm). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/prune.md

@@ -0,0 +1,34 @@
+# vp pm prune
+
+Remove unnecessary installed packages.
+
+```bash
+vp pm prune
+vp pm prune --prod
+```
+
+## Options
+
+| Option          | Description                   | Notes |
+| --------------- | ----------------------------- | ----- |
+| `--prod`        | Remove devDependencies.       |       |
+| `--no-optional` | Remove optional dependencies. |       |
+
+## Compatibility
+
+- **npm:** `npm prune`.
+- **pnpm:** `pnpm prune`.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** No command. Warns and exits successfully without performing the operation.
+- **Bun:** 1.4 or later: `bun prune`. Earlier versions warn and skip.
+
+| Option          | npm        | pnpm | Yarn Classic | Yarn Modern | Bun          | Notes |
+| --------------- | ---------- | ---- | ------------ | ----------- | ------------ | ----- |
+| `--prod`        | Yes        | Yes  | No           | No          | 1.4 or later |       |
+| `--no-optional` | 7 or later | Yes  | No           | No          | 1.4 or later |       |
+
+npm 7 and later translate selection flags to `--omit=dev` and `--omit=optional`. npm 6 translates `--prod` to `--production` and does not support `--no-optional`. Bun translates `--prod` to `--production`. Yarn and older Bun remove extraneous packages during installation instead of providing a native prune command.
+
+## Native Options
+
+For native options, see [npm prune](https://docs.npmjs.com/cli/v11/commands/npm-prune), [pnpm prune](https://pnpm.io/cli/prune), and [Bun prune](https://bun.com/docs/pm/cli/prune). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/publish.md

@@ -0,0 +1,61 @@
+# vp pm publish
+
+Publish a package to a registry. Supported targets and preview options depend on the package manager:
+
+```bash
+vp pm publish --dry-run
+vp pm publish --access public --tag next
+vp pm publish ./package.tgz
+```
+
+## Options
+
+| Option                          | Description                                  | Notes                                         |
+| ------------------------------- | -------------------------------------------- | --------------------------------------------- |
+| `--dry-run`                     | Preview without publishing.                  |                                               |
+| `--tag <tag>`                   | Select a distribution tag.                   |                                               |
+| `--access <public\|restricted>` | Request public or restricted package access. |                                               |
+| `--otp <otp>`                   | Supply a one-time password.                  |                                               |
+| `--no-git-checks`               | Skip git checks.                             |                                               |
+| `--publish-branch <branch>`     | Set the branch name to publish from.         |                                               |
+| `--report-summary`              | Save publish summary.                        |                                               |
+| `--provenance`                  | Publish with provenance.                     | Requires a compatible publishing environment. |
+| `--force`                       | Request native forced publishing.            |                                               |
+| `--json`                        | Request native JSON output.                  | Output retains the native schema.             |
+| `-r, --recursive`               | Publish all workspace packages.              |                                               |
+| `--filter <pattern>`            | Select workspaces by pattern.                | Can be repeated.                              |
+
+## Compatibility
+
+- **npm:** `npm publish`.
+- **pnpm:** `pnpm publish`.
+- **Yarn Classic:** `yarn publish`.
+- **Yarn Modern:** `yarn npm publish` for the active workspace. Explicit tarball or folder targets are rejected.
+- **Bun:** `bun publish`.
+
+| Option                          | npm             | pnpm                              | Yarn Classic    | Yarn Modern    | Bun | Notes |
+| ------------------------------- | --------------- | --------------------------------- | --------------- | -------------- | --- | ----- |
+| `--dry-run`                     | 5.10.0 or later | Yes                               | No              | 4.9.3 or later | Yes |       |
+| `--tag <tag>`                   | Yes             | Yes                               | Yes             | Yes            | Yes |       |
+| `--access <public\|restricted>` | Yes             | Yes                               | Yes             | Yes            | Yes |       |
+| `--otp <otp>`                   | Yes             | Yes                               | 1.12.1 or later | 3.2.0 or later | Yes |       |
+| `--no-git-checks`               | No              | Yes                               | No              | No             | No  |       |
+| `--publish-branch <branch>`     | No              | Yes                               | No              | No             | No  |       |
+| `--report-summary`              | No              | Yes                               | No              | No             | No  |       |
+| `--provenance`                  | 9.5.0 or later  | Yes                               | No              | 4.9.0 or later | No  |       |
+| `--force`                       | Yes             | Yes                               | No              | No             | No  |       |
+| `--json`                        | Yes             | Before 11.0.0 or 11.0.7 and later | Yes             | 4.9.3 or later | No  |       |
+| `-r, --recursive`               | 7.13.0 or later | Yes                               | No              | No             | No  |       |
+| `--filter <pattern>`            | 7.13.0 or later | Yes                               | No              | No             | No  |       |
+
+Yarn publishing uses Yarn's registry configuration and credentials. Unsupported targets and workspace selection cause an error rather than falling back to npm. Native publish failures are not retried through npm.
+
+Vite+ rejects unsupported options before the native publish command runs. Yarn Classic can ignore `--dry-run` and publish for real, or accept `--provenance` without producing an attestation. Vite+ rejects both options on Yarn Classic.
+
+Arguments after `--` are passed directly to the native command without these checks. Passing an unsupported safety option this way can result in a real publication or a publication without provenance.
+
+For a workflow that separates CI uploads from maintainer approval, use [stage](./stage).
+
+## Native Options
+
+For native options, see [npm publish](https://docs.npmjs.com/cli/v11/commands/npm-publish), [pnpm publish](https://pnpm.io/cli/publish), [Yarn Classic publish](https://classic.yarnpkg.com/en/docs/cli/publish), [Yarn npm publish](https://yarnpkg.com/cli/npm/publish), and [Bun publish](https://bun.com/docs/pm/cli/publish). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/rebuild.md

@@ -0,0 +1,31 @@
+# vp rebuild
+
+Rebuild installed packages, for example after switching Node.js versions or when a native addon needs recompilation. This top-level command requires the global CLI. Both the global and project-local CLI accept `vp pm rebuild` and its alias `vp pm rb`.
+
+```bash
+vp rebuild
+vp rebuild better-sqlite3 sharp
+vp rebuild -- --update-binary
+```
+
+## Options
+
+Supply package names to rebuild only those packages. Omit them to request a full rebuild. There are no additional Vite+ options.
+
+There are no command-specific options.
+
+## Compatibility
+
+- **npm:** `npm rebuild`.
+- **pnpm:** `pnpm rebuild`.
+- **Yarn Classic:** No command. Warns and exits successfully without performing the operation.
+- **Yarn Modern:** `yarn rebuild`.
+- **Bun:** No command. Warns and exits successfully without performing the operation.
+
+With pnpm 10 and later, a bare rebuild respects build-script approvals. Naming a package explicitly bypasses that approval gate, so rebuild only packages whose scripts you trust.
+
+On npm 12, [approving a dependency's scripts](./approve-builds) records policy but does not execute scripts skipped by an earlier install. Rebuild that package after approval.
+
+## Native Options
+
+For native options, see [npm rebuild](https://docs.npmjs.com/cli/v11/commands/npm-rebuild), [pnpm rebuild](https://pnpm.io/cli/rebuild), and [Yarn rebuild](https://yarnpkg.com/cli/rebuild). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/remove.md

@@ -0,0 +1,47 @@
+# vp remove
+
+Remove dependencies from the project. Aliases: `vp rm`, `vp un`, and `vp uninstall`.
+
+```bash
+vp remove react
+vp remove --filter web react
+vp remove -g --dry-run typescript
+```
+
+## Options
+
+| Option                 | Description                                              | Notes                                                                        |
+| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `-D, --save-dev`       | Remove from devDependencies.                             |                                                                              |
+| `-O, --save-optional`  | Remove from optionalDependencies.                        |                                                                              |
+| `-P, --save-prod`      | Remove from dependencies.                                |                                                                              |
+| `--filter <pattern>`   | Select workspaces by pattern.                            | Can be repeated.                                                             |
+| `-w, --workspace-root` | Remove from workspace root.                              |                                                                              |
+| `-r, --recursive`      | Remove recursively from all workspace packages.          |                                                                              |
+| `-g, --global`         | Remove global packages.                                  | Requires the global CLI. Uses the [global package store](./global-packages). |
+| `--dry-run`            | Preview what would be removed without actually removing. | Requires --global.                                                           |
+
+## Compatibility
+
+The commands below describe project operations. Global mode is described under [Options](#options).
+
+- **npm:** `npm uninstall`.
+- **pnpm:** `pnpm remove`.
+- **Yarn Classic:** `yarn remove`.
+- **Yarn Modern:** `yarn remove`.
+- **Bun:** `bun remove`.
+
+| Option                 | npm             | pnpm | Yarn Classic | Yarn Modern | Bun          | Notes                            |
+| ---------------------- | --------------- | ---- | ------------ | ----------- | ------------ | -------------------------------- |
+| `-D, --save-dev`       | Yes             | Yes  | No           | No          | No           |                                  |
+| `-O, --save-optional`  | Yes             | Yes  | No           | No          | No           |                                  |
+| `-P, --save-prod`      | Yes             | Yes  | No           | No          | No           |                                  |
+| `--filter <pattern>`   | 7.14.0 or later | Yes  | One filter   | Yes         | 1.4 or later |                                  |
+| `-w, --workspace-root` | 8.1.0 or later  | Yes  | No           | No          | No           |                                  |
+| `-r, --recursive`      | 8.1.0 or later  | Yes  | No           | Yes         | No           | npm includes the workspace root. |
+| `-g, --global`         | Yes             | Yes  | Yes          | Yes         | Yes          |                                  |
+| `--dry-run`            | Yes             | Yes  | Yes          | Yes         | Yes          |                                  |
+
+## Native Options
+
+For native options, see [npm uninstall](https://docs.npmjs.com/cli/v11/commands/npm-uninstall), [pnpm remove](https://pnpm.io/cli/remove), [Yarn remove](https://yarnpkg.com/cli/remove), [Yarn Classic remove](https://classic.yarnpkg.com/en/docs/cli/remove), and [Bun remove](https://bun.com/docs/pm/cli/remove). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/search.md

@@ -0,0 +1,38 @@
+# vp pm search
+
+Search the package registry.
+
+```bash
+vp pm search vite plugin
+vp pm search typescript --json
+```
+
+## Options
+
+At least one search term is required.
+
+| Option             | Description                 | Notes                             |
+| ------------------ | --------------------------- | --------------------------------- |
+| `--json`           | Request native JSON output. | Output retains the native schema. |
+| `--long`           | Show extended information.  |                                   |
+| `--registry <url>` | Select the registry.        |                                   |
+
+## Compatibility
+
+- **npm:** `npm search`.
+- **pnpm:** 11 or later: `pnpm search`. Earlier versions use `npm search` as a fallback.
+- **Yarn Classic:** Fallback: `npm search`.
+- **Yarn Modern:** Fallback: `npm search`.
+- **Bun:** Fallback: `npm search`.
+
+| Option             | npm | pnpm      | Yarn Classic | Yarn Modern | Bun | Notes |
+| ------------------ | --- | --------- | ------------ | ----------- | --- | ----- |
+| `--json`           | Yes | Yes       | Yes          | Yes         | Yes |       |
+| `--long`           | Yes | Before 11 | Yes          | Yes         | Yes |       |
+| `--registry <url>` | Yes | Yes       | Yes          | Yes         | Yes |       |
+
+Registry settings and output follow the command that runs.
+
+## Native Options
+
+For native options, see [npm search](https://docs.npmjs.com/cli/v11/commands/npm-search) and [pnpm search](https://pnpm.io/cli/search). To pass these options through Vite+, see [Native Arguments](./#native-arguments).

package/docs/guide/package-management/stage.md

@@ -0,0 +1,175 @@
+# vp pm stage
+
+Use staged publishing to separate a package upload from its release. A CI job can upload a staged version without 2FA, then a maintainer approves or rejects it from a trusted device with 2FA.
+
+```bash
+vp pm stage publish --dry-run
+vp pm stage publish
+vp pm stage list
+vp pm stage view <stage-id>
+vp pm stage download <stage-id>
+vp pm stage approve <stage-id>
+vp pm stage reject <stage-id>
+```
+
+## Options
+
+Use the subcommands below to upload, inspect, approve, or reject staged versions.
+
+### `publish`
+
+Upload a package. Accepts an optional tarball or folder target.
+
+| Option                          | Description                                  | Notes                                         |
+| ------------------------------- | -------------------------------------------- | --------------------------------------------- |
+| `--tag <tag>`                   | Publish tag.                                 |                                               |
+| `--access <public\|restricted>` | Request public or restricted package access. |                                               |
+| `--otp <otp>`                   | Supply a one-time password.                  |                                               |
+| `--dry-run`                     | Preview without staging.                     |                                               |
+| `--json`                        | Request native JSON output.                  | Output retains the native schema.             |
+| `-r, --recursive`               | Stage all publishable workspace packages.    |                                               |
+| `--filter <pattern>`            | Select workspaces by pattern.                | Can be repeated.                              |
+| `--provenance`                  | Stage with provenance.                       | Requires a compatible publishing environment. |
+| `--registry <url>`              | Select the registry.                         |                                               |
+
+### `list`
+
+List staged versions. Accepts an optional package specification. Alias: `ls`.
+
+| Option             | Description                 | Notes                             |
+| ------------------ | --------------------------- | --------------------------------- |
+| `--json`           | Request native JSON output. | Output retains the native schema. |
+| `--registry <url>` | Select the registry.        |                                   |
+
+### `view`
+
+Inspect a staged version. Requires a stage ID.
+
+| Option             | Description                 | Notes                             |
+| ------------------ | --------------------------- | --------------------------------- |
+| `--json`           | Request native JSON output. | Output retains the native schema. |
+| `--registry <url>` | Select the registry.        |                                   |
+
+### `download`
+
+Download a staged tarball. Requires a stage ID.
+
+| Option             | Description          | Notes |
+| ------------------ | -------------------- | ----- |
+| `--registry <url>` | Select the registry. |       |
+
+### `approve`
+
+Promote a staged version to the live registry. Requires a stage ID.
+
+| Option             | Description                 | Notes |
+| ------------------ | --------------------------- | ----- |
+| `--otp <otp>`      | Supply a one-time password. |       |
+| `--registry <url>` | Select the registry.        |       |
+
+### `reject`
+
+Discard a staged version. Requires a stage ID.
+
+| Option             | Description                 | Notes |
+| ------------------ | --------------------------- | ----- |
+| `--otp <otp>`      | Supply a one-time password. |       |
+| `--registry <url>` | Select the registry.        |       |
+
+## Compatibility
+
+All npm paths, including fallbacks, require npm 11.15 or later and Node.js 22.14 or later.
+
+### `publish`
+
+- **npm:** 11.15 or later: `npm stage publish`. Earlier versions warn and skip.
+- **pnpm:** 11.3 or later: `pnpm stage publish`. Earlier versions warn and skip.
+- **Yarn Classic:** Fallback: `npm stage publish`.
+- **Yarn Modern:** 4.16.0 or later: `yarn npm publish --staged`. Earlier versions use `npm stage publish` as a fallback. Explicit targets use npm fallback.
+- **Bun:** Fallback: `npm stage publish`.
+
+| Option                          | npm                     | pnpm | Yarn Classic            | Yarn Modern                               | Bun                     | Notes                                            |
+| ------------------------------- | ----------------------- | ---- | ----------------------- | ----------------------------------------- | ----------------------- | ------------------------------------------------ |
+| `--tag <tag>`                   | Yes                     | Yes  | Yes                     | Yes                                       | Yes                     |                                                  |
+| `--access <public\|restricted>` | Yes                     | Yes  | Yes                     | Yes                                       | Yes                     |                                                  |
+| `--otp <otp>`                   | Yes                     | Yes  | Yes                     | Yes                                       | Yes                     |                                                  |
+| `--dry-run`                     | Yes                     | Yes  | Yes                     | Yes                                       | Yes                     |                                                  |
+| `--json`                        | Yes                     | Yes  | Yes                     | Yes                                       | Yes                     |                                                  |
+| `-r, --recursive`               | No target or target `.` | Yes  | No target or target `.` | Before 4.16 with no target, or target `.` | No target or target `.` |                                                  |
+| `--filter <pattern>`            | No target or target `.` | Yes  | No target or target `.` | Before 4.16 with no target, or target `.` | No target or target `.` |                                                  |
+| `--provenance`                  | Yes                     | Yes  | Yes                     | Yes                                       | Yes                     |                                                  |
+| `--registry <url>`              | Yes                     | Yes  | Yes                     | Before 4.16, or an explicit target        | Yes                     | Use Yarn registry settings on native Yarn paths. |
+
+### `list`
+
+- **npm:** 11.15 or later: `npm stage list`. Earlier versions warn and skip.
+- **pnpm:** 11.3 or later: `pnpm stage list`. Earlier versions warn and skip.
+- **Yarn Classic:** Fallback: `npm stage list`.
+- **Yarn Modern:** 4.16.0 or later: `yarn npm stage list`. Earlier versions use `npm stage list` as a fallback.
+- **Bun:** Fallback: `npm stage list`.
+
+| Option             | npm | pnpm | Yarn Classic | Yarn Modern   | Bun | Notes                                            |
+| ------------------ | --- | ---- | ------------ | ------------- | --- | ------------------------------------------------ |
+| `--json`           | Yes | Yes  | Yes          | Yes           | Yes |                                                  |
+| `--registry <url>` | Yes | Yes  | Yes          | Before 4.16.0 | Yes | Use Yarn registry settings on native Yarn paths. |
+
+### `view`
+
+- **npm:** 11.15 or later: `npm stage view`. Earlier versions warn and skip.
+- **pnpm:** 11.3 or later: `pnpm stage view`. Earlier versions warn and skip.
+- **Yarn Classic:** Fallback: `npm stage view`.
+- **Yarn Modern:** Fallback: `npm stage view`.
+- **Bun:** Fallback: `npm stage view`.
+
+| Option             | npm | pnpm | Yarn Classic | Yarn Modern | Bun | Notes |
+| ------------------ | --- | ---- | ------------ | ----------- | --- | ----- |
+| `--json`           | Yes | Yes  | Yes          | Yes         | Yes |       |
+| `--registry <url>` | Yes | Yes  | Yes          | Yes         | Yes |       |
+
+### `download`
+
+- **npm:** 11.15 or later: `npm stage download`. Earlier versions warn and skip.
+- **pnpm:** 11.3 or later: `pnpm stage download`. Earlier versions warn and skip.
+- **Yarn Classic:** Fallback: `npm stage download`.
+- **Yarn Modern:** Fallback: `npm stage download`.
+- **Bun:** Fallback: `npm stage download`.
+
+| Option             | npm | pnpm | Yarn Classic | Yarn Modern | Bun | Notes |
+| ------------------ | --- | ---- | ------------ | ----------- | --- | ----- |
+| `--registry <url>` | Yes | Yes  | Yes          | Yes         | Yes |       |
+
+### `approve`
+
+- **npm:** 11.15 or later: `npm stage approve`. Earlier versions warn and skip.
+- **pnpm:** 11.3 or later: `pnpm stage approve`. Earlier versions warn and skip.
+- **Yarn Classic:** Fallback: `npm stage approve`.
+- **Yarn Modern:** 4.16.0 or later: `yarn npm stage approve`. Earlier versions use `npm stage approve` as a fallback.
+- **Bun:** Fallback: `npm stage approve`.
+
+| Option             | npm | pnpm | Yarn Classic | Yarn Modern   | Bun | Notes                                            |
+| ------------------ | --- | ---- | ------------ | ------------- | --- | ------------------------------------------------ |
+| `--otp <otp>`      | Yes | Yes  | Yes          | Yes           | Yes |                                                  |
+| `--registry <url>` | Yes | Yes  | Yes          | Before 4.16.0 | Yes | Use Yarn registry settings on native Yarn paths. |
+
+### `reject`
+
+- **npm:** 11.15 or later: `npm stage reject`. Earlier versions warn and skip.
+- **pnpm:** 11.3 or later: `pnpm stage reject`. Earlier versions warn and skip.
+- **Yarn Classic:** Fallback: `npm stage reject`.
+- **Yarn Modern:** 4.16.0 or later: `yarn npm stage reject`. Earlier versions use `npm stage reject` as a fallback.
+- **Bun:** Fallback: `npm stage reject`.
+
+| Option             | npm | pnpm | Yarn Classic | Yarn Modern   | Bun | Notes                                            |
+| ------------------ | --- | ---- | ------------ | ------------- | --- | ------------------------------------------------ |
+| `--otp <otp>`      | Yes | Yes  | Yes          | Yes           | Yes |                                                  |
+| `--registry <url>` | Yes | Yes  | Yes          | Before 4.16.0 | Yes | Use Yarn registry settings on native Yarn paths. |
+
+Yarn fallback paths and Bun warn before invoking npm.
+
+This command is unrelated to Yarn's version-control staging command or Vite+'s staged-file checks.
+
+## Native Options
+
+For native options, see [npm stage](https://docs.npmjs.com/cli/v11/commands/npm-stage), [pnpm stage](https://pnpm.io/cli/stage), [Yarn npm publish](https://yarnpkg.com/cli/npm/publish), [Yarn npm stage list](https://yarnpkg.com/cli/npm/stage/list), [Yarn npm stage approve](https://yarnpkg.com/cli/npm/stage/approve), and [Yarn npm stage reject](https://yarnpkg.com/cli/npm/stage/reject). To pass these options through Vite+, see [Native Arguments](./#native-arguments).
+
+For the registry workflow, see [npm staged publishing](https://docs.npmjs.com/staged-publishing).