diff --git a/docs/guide/upgrade.md b/docs/guide/upgrade.md index 1e834cb3b6..34b938380a 100644 --- a/docs/guide/upgrade.md +++ b/docs/guide/upgrade.md @@ -32,48 +32,70 @@ Older versions are pruned automatically after each upgrade. The active version a ## Local `vite-plus` -Update the project dependency with the package manager commands in Vite+: +The recommended way to upgrade an existing Vite+ project is `vp migrate`: ```bash -vp update vite-plus +vp migrate ``` -You can also use `vp add vite-plus@latest` if you want to move the dependency explicitly to the latest version. +On a project that is already on Vite+, migrate does a toolchain version upgrade only: it re-pins `vite-plus`, the `vite` -> `@voidzero-dev/vite-plus-core` alias, and the `vitest` pin to the versions the global `vp` now bundles, across every workspace package. It skips the first-time setup steps (git hooks, editor and agent files, lint migration), so a version bump does not re-touch things you already configured. Pass `--full` to also run that setup. -### Updating Aliased Packages +### Updating the Vitest Pin + +If you migrated with `vp migrate`, your project pins `vitest` to an exact version so the whole project shares a single Vitest copy with the bundled `vp test` runner. The pin lives in your package manager's override block: -Vite+ sets up an npm alias for its core package during installation: +- **npm / Bun:** a `vitest` entry under `overrides` in `package.json` +- **Yarn:** a `vitest` entry under `resolutions` in `package.json` +- **pnpm:** a `vitest` entry under `overrides` in `pnpm-workspace.yaml` — unless your `package.json` already had a `pnpm` field, in which case it lives under `pnpm.overrides` in `package.json` instead (pnpm ignores `pnpm-workspace.yaml` overrides when `package.json` defines `pnpm.overrides`) -- `vite` is aliased to `npm:@voidzero-dev/vite-plus-core@latest` +A Vite+ release can bump the bundled Vitest. Because that pin also applies to `vite-plus`'s own `vitest` dependency, an out-of-date pin keeps installing the previous runner even after you upgrade `vite-plus` — splitting Vitest's internals (mocks, `expect`, runner state) between the pinned copy and the one `vp test` loads. -`vp update vite-plus` does not re-resolve this alias in the lockfile. To fully upgrade, update it separately: +After upgrading `vite-plus`, re-pin `vitest` to the version Vite+ now bundles. Check that version with: ```bash -vp update @voidzero-dev/vite-plus-core +vp --version ``` -Or update everything at once: +Then set the `vitest` override to that exact version, or rerun `vp migrate` to update the pin for you. + +## Preview Builds + +Some Vite+ pull requests publish temporary packages for testing before an npm release. Treat these as nightly or bleeding-edge builds: they are useful when you want to verify a specific fix, test a fresh upstream dependency bump, or confirm a change before the next release. For day-to-day work, prefer the published `latest` release. + +Each commit on an eligible pull request is published to [pkg.pr.new](https://pkg.pr.new) and registered with the [registry bridge](https://registry-bridge.viteplus.dev/). The bridge serves these builds as ordinary npm versions of the form `0.0.0-commit.` and proxies every other package to the npm registry. That means you install a preview with normal version specs instead of mutable URLs, and the same versions resolve in CI. + +Both `vite-plus` and `@voidzero-dev/vite-plus-core` publish under the same `0.0.0-commit.` version. Each pull request carries a comment listing the exact version for its latest commit, along with ready-to-copy install steps. + +You can find preview builds in pull requests that automatically update upstream dependencies. For examples, search the merged pull requests for [upstream dependency updates](https://github.com/voidzero-dev/vite-plus/pulls?q=is%3Apr+is%3Amerged+upgrade+upstream+dependencies). + +Preview builds are addressed by pull request number or commit SHA. They are not a stable version range, and you should avoid leaving them in long-lived branches unless a maintainer asks you to. + +### Global `vp` Preview + +Install a preview build of the global CLI by passing `VP_PR_VERSION` to the installer. Pass a pull request number or a commit SHA: ```bash -vp update vite-plus @voidzero-dev/vite-plus-core +curl -fsSL https://vite.plus | VP_PR_VERSION= bash ``` -You can verify with `vp outdated` that no Vite+ packages remain outdated. +On Windows: -### Updating the Vitest Pin +```powershell +$env:VP_PR_VERSION = "" +irm https://vite.plus/ps1 | iex +Remove-Item Env:\VP_PR_VERSION +``` -If you migrated with `vp migrate`, your project pins `vitest` to an exact version so the whole project shares a single Vitest copy with the bundled `vp test` runner. The pin lives in your package manager's override block: +The installer resolves the ref to its `0.0.0-commit.` build through the registry bridge and installs it like any other version. Run `vp --version` afterward to confirm which build and bundled tool versions are active. When you are done testing, return to the published release with `vp upgrade --force` or by running the installer again without `VP_PR_VERSION`. -- **npm / Bun:** a `vitest` entry under `overrides` in `package.json` -- **Yarn:** a `vitest` entry under `resolutions` in `package.json` -- **pnpm:** a `vitest` entry under `overrides` in `pnpm-workspace.yaml` — unless your `package.json` already had a `pnpm` field, in which case it lives under `pnpm.overrides` in `package.json` instead (pnpm ignores `pnpm-workspace.yaml` overrides when `package.json` defines `pnpm.overrides`) - -A Vite+ release can bump the bundled Vitest. Because that pin also applies to `vite-plus`'s own `vitest` dependency, an out-of-date pin keeps installing the previous runner even after you upgrade `vite-plus` — splitting Vitest's internals (mocks, `expect`, runner state) between the pinned copy and the one `vp test` loads. +### Local `vite-plus` Preview -After upgrading `vite-plus`, re-pin `vitest` to the version Vite+ now bundles. Check that version with: +After installing the preview global CLI above, run migrate in the project to move its local `vite-plus` onto the same build: ```bash -vp --version +vp migrate ``` -Then set the `vitest` override to that exact version, or rerun `vp migrate` to update the pin for you. +Migrate points the project at the bridge registry (writing it to `.npmrc`, or `.yarnrc.yml` for Yarn Berry) and pins `vite-plus` and the `vite` -> `@voidzero-dev/vite-plus-core` alias to the matching `0.0.0-commit.` version. That registry line is what lets the same versions resolve in the project's own CI, so commit it if you want CI to test the preview too. + +After installing, check the bundled versions with `vp --version`. When testing is complete, restore the published release: set `vite-plus` back to `latest`, remove the bridge `registry` line from `.npmrc` (or `.yarnrc.yml`), and reinstall with `vp install`.