vite-plus 0.2.1 → 0.2.2

package/docs/guide/migrate-rules.md

@@ -0,0 +1,347 @@
+# Migration Rules
+
+This reference describes exactly what `vp migrate` does to a project: how it
+updates dependencies, rewrites source imports and package scripts, and adjusts
+package-manager configuration. See the [migration guide](./migrate.md) for the
+command overview and workflow.
+
+Except for [Before You Migrate](#before-you-migrate), which lists steps you
+take yourself, everything below describes automatic behavior.
+
+## Before You Migrate
+
+1. Run `vp upgrade` so the global CLI has the latest migration rules. A stale
+   local `vite-plus` is not a blocker: when the project's local copy is older,
+   migration delegates to the global CLI.
+2. Upgrade the project to Vite 8+ and Vitest 4.1+ when necessary.
+3. Run `vp migrate` from the workspace root. Use `--no-interactive` in
+   automated environments.
+4. Review every changed manifest, package-manager config, source rewrite, and
+   generated lockfile.
+5. Validate with `vp install`, `vp check`, `vp test`, and `vp build`.
+
+Migration is idempotent: running it again after a successful migration should
+not produce another diff.
+
+## Upgrade vs. Full Setup
+
+On a project that already depends on `vite-plus`, `vp migrate` performs an
+upgrade only: it updates dependencies and package-manager configuration and
+finalizes imports. It does not touch project setup.
+
+- `--full` also runs the setup actions: git hooks, editor config, agent files,
+  ESLint and Prettier migration, framework shims, the tsconfig `baseUrl` fix,
+  and the `.nvmrc`/Volta to `.node-version` conversion.
+- `--hooks`, `--agent`, and `--editor` opt into a single setup action without
+  `--full`.
+
+When a default upgrade skips setup actions that would apply, it prints a hint
+to run `vp migrate --full`. Fresh (non Vite+) projects always run the full
+migration.
+
+## Dependency Rules
+
+What happens to each toolchain dependency, at a glance:
+
+| Dependency                     | What happens                                                                                                                                                            |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vite-plus`                    | Added where the package is migrated; plain ranges re-pinned to the concrete target, directly or through a catalog.                                                      |
+| `vite`                         | Existing declarations kept and pointed at the core alias. Under pnpm, added as a direct dev dependency wherever needed (see [Vite and Overrides](#vite-and-overrides)). |
+| `vitest`                       | Removed in the common node-mode case because `vite-plus` provides it transitively. Kept or added only when [directly required](#when-vitest-is-directly-required).      |
+| `@vitest/*`                    | Directly installed lockstep packages aligned to the bundled Vitest version (see [Vitest Ecosystem Packages](#vitest-ecosystem-packages)).                               |
+| `@voidzero-dev/vite-plus-test` | Removed everywhere: dependencies, overrides, resolutions, and catalog aliases. Imports are rewritten to the current `vite-plus/test*` surface.                          |
+
+### Version Selection
+
+- `vite-plus` is pinned to the concrete version of the CLI running the
+  migration, never the `latest` dist-tag.
+- The `vite` alias targets `@voidzero-dev/vite-plus-core` from the same Vite+
+  release.
+- A catalog-backed manifest may contain `catalog:` or a named catalog
+  reference. Migration keeps the reference and updates the referenced catalog
+  value to the concrete toolchain target.
+- Deliberate protocol pins are preserved: `workspace:`, `file:`, `link:`,
+  `npm:`, `github:`, Git URLs, and HTTP URLs.
+- Migration reconciles every workspace package, not only the root manifest.
+  Shared overrides and catalogs stay at the workspace root; dependencies that
+  provide a peer belong in each package that needs them.
+
+### Vite and Overrides
+
+Package-manager overrides do not create dependency edges by themselves. Under
+pnpm, a package that lists `vite-plus` in `dependencies` or `devDependencies`
+but has no `vite` entry anywhere (`dependencies`, `devDependencies`,
+`optionalDependencies`, or `peerDependencies`) lets pnpm auto-install upstream
+Vite to satisfy Vitest's required `vite` peer, splitting the project across
+separate Vite+, Vite, and Vitest instances. To prevent this, `vp migrate` adds
+the missing `vite` entry to `devDependencies` of every such package; the
+workspace override then redirects it to Vite+ core.
+
+Related rules:
+
+- A direct `vite` declaration is never removed merely because a root override
+  exists.
+- Plain or stale aliases are normalized; named catalog references are kept.
+- The direct-entry rule above is pnpm-specific. Bun mirrors its core alias as
+  a direct dependency for its peer resolver, and npm browser-provider layouts
+  may need a top-level `vite` edge so nested Vitest packages can resolve
+  `vite`.
+
+### When Vitest Is Directly Required
+
+Migration keeps or adds a package-local `vitest` at the exact bundled version
+when any of the following is true:
+
+- an installed dependency has a non-optional `vitest` peer, whether exact or a
+  range;
+- the package uses Vitest browser mode or an opt-in browser provider;
+- source or TypeScript configuration retains an upstream `vitest` reference;
+- the package declares `@nuxt/test-utils`; or
+- dependency metadata is unavailable and an existing direct `vitest` might be
+  satisfying an unknown required peer.
+
+Detection reads installed peer metadata, so integrations such as
+`vite-plugin-gherkin` are handled even though their names do not contain
+`vitest`.
+
+When a package qualifies, migration:
+
+- adds `vitest` to that package, not indiscriminately to every workspace
+  package;
+- uses the existing catalog reference when supported, otherwise the exact
+  bundled version; and
+- keeps a matching workspace override or resolution so the graph resolves a
+  single Vitest version.
+
+A peer declaration alone does not install Vitest. If a surviving
+`peerDependencies.vitest` uses a catalog entry that migration will remove, it
+is resolved to the public peer range first.
+
+### Vitest Ecosystem Packages
+
+Official current `@vitest/*` packages generally publish in lockstep with
+Vitest. Migration aligns the ones the project directly installs, including
+`@vitest/coverage-v8`, `@vitest/coverage-istanbul`, `@vitest/ui`, and
+`@vitest/web-worker`:
+
+- when the package manager supports catalogs, they are referenced through the
+  toolchain catalog: an existing `catalog:` / `catalog:<name>` reference is
+  preserved, a catalog entry is added for any package that lacks one, and each
+  entry is updated to the bundled Vitest version;
+- when catalogs are unsupported (npm, a standalone bun project, or a
+  pre-catalog pnpm/Yarn), the concrete bundled version is written instead.
+
+Packages that are **not** aligned:
+
+- `@vitest/eslint-plugin` follows its own version line;
+- `@vitest/coverage-c8` stopped at an older release and has no Vitest 4
+  version; and
+- third-party `vitest-*` integrations keep their own compatible versions,
+  though their required Vitest peer may still trigger
+  [direct provisioning](#when-vitest-is-directly-required).
+
+For browser mode, the base `@vitest/browser` runtime and
+`@vitest/browser-preview` are bundled by Vite+ and are removed as direct
+dependencies. The Playwright and WebdriverIO providers stay opt-in: a kept or
+injected provider is referenced through the preferred toolchain catalog at the
+bundled Vitest version (or written concretely when catalogs are unsupported),
+and its `playwright` or `webdriverio` peer is installed alongside.
+
+Providers are detected before imports are rewritten. This covers legacy
+projects that aliased `vitest` to `@voidzero-dev/vite-plus-test` and import
+from `vitest/browser-<provider>`, `vitest/browser/providers/<provider>`, or
+`vitest/plugins/browser-<provider>`: those imports still install the
+corresponding `@vitest/browser-playwright` or `@vitest/browser-webdriverio`
+dependency and its framework peer.
+
+Object-valued nested npm and Bun overrides are preserved: they are
+user-defined scopes rather than scalar version pins.
+
+## Source Rewrite Rules
+
+### `vite` Imports
+
+`vite` and `vite/*` imports are rewritten to `vite-plus` **only in config
+entry files**: `vite.config.*`, `vitest.config.*`, and any config file the
+migration resolved. Every other file keeps its `vite` imports, for two
+reasons:
+
+- `vite-plus` is not a guaranteed superset of Vite's exposed surface. It owns
+  only `defineConfig`, `defineProject`, and `lazyPlugins`, so rewriting a
+  pass-through symbol such as `createBuilder` or `loadConfigFromFile`
+  (including in `typeof import('vite')` type positions) can break.
+- An unrewritten `vite` import still resolves through the
+  `@voidzero-dev/vite-plus-core` alias in a Vite+ project.
+
+Plugin packages (an unscoped name starting with `vite-plugin-` or
+`unplugin-`, or `vite` in `peerDependencies`/`dependencies`) skip the rewrite
+even in config files. Only the `vite` specifier is in scope for this rule.
+
+`declare module 'vite'` augmentations follow the same rule and are preserved
+outside config files. Through the core alias they reach the same
+`@voidzero-dev/vite-plus-core` module whose `UserConfig` types `defineConfig`
+from `vite-plus`, so they keep working after migration; `vite-plus` itself
+exports no `UserConfig` symbol, so a rewritten `declare module 'vite-plus'`
+augmentation would merge with nothing. Extensions aimed at `vite-plus`'s own
+surface are written against `vite-plus` by hand.
+
+### `vitest` and Browser Imports
+
+- Ordinary `vitest` and `vitest/*` imports are rewritten to
+  `vite-plus/test*`.
+- Legacy Playwright and WebdriverIO provider imports are detected before this
+  rewrite so their optional provider dependencies are not lost.
+- Scoped `@vitest/browser*` imports are rewritten to the corresponding
+  `vite-plus/test/browser*` exports, provisioning opt-in providers when
+  needed.
+- Existing `vite-plus/test*` imports are left unchanged.
+
+### What Is Never Rewritten
+
+- `declare module 'vitest'` and `declare module '@vitest/browser*'`: module
+  augmentation must retain the upstream module identity.
+- References that stay behind, such as `compilerOptions.types`,
+  `require.resolve`, `import.meta.resolve`, and `vitest/package.json`,
+  require package-local Vitest (see
+  [When Vitest Is Directly Required](#when-vitest-is-directly-required)).
+- In a package that declares `@nuxt/test-utils`, every `vitest` and
+  `vitest/*` module specifier is preserved package-wide: the Nuxt transform
+  requires the upstream identity and can otherwise inject a duplicate `vi`
+  import. This exception does not apply to sibling packages or to scoped
+  `@vitest/browser*` imports.
+
+The `prefer-vite-plus-imports` lint rule follows the same Nuxt exception, so
+lint autofix preserves these imports too.
+
+## Package Script Rewrite Rules
+
+Migration rewrites commands provided by the Vite+ toolchain in `package.json`
+scripts while preserving their arguments:
+
+| Before        | After                                       |
+| ------------- | ------------------------------------------- |
+| `vite`        | `vp dev`, or the matching `vp` subcommand   |
+| `vitest`      | `vp test`                                   |
+| `oxlint`      | `vp lint`                                   |
+| `oxfmt`       | `vp fmt`                                    |
+| `tsdown`      | `vp pack`                                   |
+| `lint-staged` | `vp staged`                                 |
+| `eslint`      | `vp lint`, when its optional migration runs |
+| `prettier`    | `vp fmt`, when its optional migration runs  |
+
+For commands launched through `bunx`, migration preserves `bunx` and its
+`--bun` flag (keeping the user's chosen runtime) and rewrites only the managed
+command. This also works when `bunx` follows a command-launcher delimiter such
+as `run` or `--`:
+
+| Before                                                  | After                                                    |
+| ------------------------------------------------------- | -------------------------------------------------------- |
+| `bunx --bun vite build`                                 | `bunx --bun vp build`                                    |
+| `bunx --bun vitest run`                                 | `bunx --bun vp test run`                                 |
+| `portless --tailscale run bunx --bun vite`              | `portless --tailscale run bunx --bun vp dev`             |
+| `dotenv -e .env.test -- bunx --bun oxlint --type-aware` | `dotenv -e .env.test -- bunx --bun vp lint --type-aware` |
+
+Unrelated `bunx` commands and other package-executor forms remain unchanged.
+
+## Node.js Version Rules
+
+Migration converts legacy Node.js version-manager files to `.node-version`,
+the format Vite+ reads. On an existing Vite+ project this conversion is part
+of the full setup bucket, so it runs with `vp migrate --full`; fresh
+migrations run it unconditionally.
+
+- `.nvmrc` and Volta `volta.node` pins are converted to `.node-version`. An
+  existing `.node-version` is kept.
+- When `.nvmrc` is removed, any `actions/setup-node` `node-version-file:
+.nvmrc` reference in `.github/workflows/*.{yml,yaml}` and composite actions
+  (`.github/actions/**/action.{yml,yaml}`) is repointed to `.node-version` so
+  CI does not fail with "node version file ... does not exist".
+
+## Package-Manager Rules
+
+### pnpm
+
+**Root settings location.** pnpm 10.6.2+ uses `pnpm-workspace.yaml` as the
+single source for supported root settings. Migration moves recognized
+`package.json#pnpm` fields there, including overrides, peer rules, patch
+settings, package extensions, architecture and build policy, audit/update
+configuration, and configuration dependencies. It removes the `pnpm` object
+when it becomes empty and preserves unknown keys that may belong to other
+tooling.
+
+- When both files define the same migrated setting, object entries are merged
+  recursively and unique array entries are retained. Values from
+  `package.json#pnpm` win at conflicting scalar leaves, while workspace-only
+  sibling entries are preserved.
+- Before pnpm 10.6.2, these settings stay in `package.json#pnpm`. (Workspace
+  settings support arrived incrementally: 10.5.0 in general, 10.5.1 for
+  overrides, 10.6.2 for `peerDependencyRules`. pnpm 11 no longer reads the
+  legacy `package.json` settings.)
+
+**Catalogs.** Catalogs are a separate feature, supported from pnpm 9.5.0,
+independent of the settings boundary above. Even below 10.6.2, where
+overrides stay in `package.json#pnpm`, migration still rewrites the workspace
+catalog off stale wrapper aliases and keeps `catalog:` overrides as
+references rather than inlining them to concrete versions.
+
+- Dependency references, default and named catalogs, overrides, and
+  `peerDependencyRules` are kept consistent with each other.
+- pnpm accepts the logical default catalog as either top-level `catalog` or
+  `catalogs.default`, but not both. Migration preserves the existing form and
+  never creates the other form beside it.
+- When an existing named catalog already owns `vite-plus`, `vite`, or
+  `vitest`, migration reuses that managed toolchain catalog for newly added
+  dependencies and overrides. It creates a top-level default catalog only
+  when no managed or default catalog can be reused.
+
+**Other rules.**
+
+- Each package that declares `vite-plus` also gets a direct `vite` dev
+  dependency (see [Vite and Overrides](#vite-and-overrides)).
+- Unrelated selector-shaped and object-valued overrides are preserved.
+
+### npm
+
+- Direct aliases are normalized before the matching override is added, so npm
+  does not fail with `EOVERRIDE`.
+- When a real Vite installation changes to the core alias, stale Vite install
+  and lockfile state is removed before reinstalling.
+- Opt-in browser-provider layouts get a top-level `vite` edge when nested
+  Vitest packages otherwise cannot resolve it.
+
+### Yarn
+
+- Vite+ does not support Plug'n'Play. Migration detects explicit and implicit
+  PnP and converts the project to `nodeLinker: node-modules`, preserving all
+  unrelated `.yarnrc.yml` settings. `--no-interactive` accepts the
+  conversion; a process-level `YARN_NODE_LINKER=pnp` must be fixed by the
+  caller.
+- Catalog references and user hoisting settings are preserved.
+- Migration avoids split Vitest copies under workspace hoisting isolation: it
+  applies a package-level fix where possible and warns when the isolation
+  cannot be changed safely.
+
+### Bun
+
+- Bun catalogs only resolve inside a workspace (a root `package.json` with a
+  non-empty `workspaces`). In a bun workspace, existing top-level or
+  workspace catalog locations and named catalog references are preserved. A
+  standalone (single-package) bun project keeps concrete specs and gets no
+  catalog field, because `bun install` cannot resolve `catalog:` outside a
+  workspace.
+- The core alias is mirrored as a direct `vite` dependency so Bun sees the
+  peer provider before applying overrides.
+
+## After the Migration
+
+- Each Vite config is inspected for Rolldown-incompatible patterns (such as
+  `manualChunks`). Anything found is reported as a warning; the config is not
+  changed.
+- Dependencies are reinstalled once to refresh the lockfile. If installation
+  fails, migration reports the error and exits with a nonzero status.
+- After a successful migration, `vp fmt` runs on the files changed during
+  migration, excluding paths that were already dirty in the Git worktree.
+  Oxfmt selects the supported formats; non-Git projects retain full-project
+  formatting. Formatting is skipped while the project still uses Prettier. A
+  formatter failure is reported as a warning so the migration result and the
+  manual formatting command remain available.

package/docs/guide/migrate.md

@@ -48,6 +48,10 @@ The `migrate` command is designed to move existing projects onto Vite+ quickly.
 - Updates scripts to the Vite+ command surface
 - Can set up commit hooks
 - Can write agent and editor configuration files
+- Formats the migrated project
+
+See [Migration Rules](./migrate-rules.md) for the exact dependency, source
+rewrite, and package-manager behavior.
 
 Most projects will require further manual adjustments after running `vp migrate`.
 
@@ -166,6 +170,16 @@ export default defineConfig({
 
 After migrating, remove lint-staged from your dependencies and delete any lint-staged config files. See the [Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details.
 
+### Git hook tools
+
+The `vp migrate` command can set up Vite+ commit hooks for you, but it doesn't automatically migrate every type of Git hook tool. This automatic migration path is specifically designed to handle Husky v9+ and lint-staged-style setups. Projects using Husky versions older than 9.0.0 are skipped and should upgrade to Husky v9 before using the automatic migration path.
+
+If your project currently uses `lefthook`, `simple-git-hooks`, or `yorkie`, `vp migrate` will leave your existing configuration alone and show a warning. This happens even if you choose to set up hooks during the prompt or include the `--hooks` flag.
+
+If you want to move one of those tools over to Vite+ manually, you can follow these steps. First, move your staged-file commands into the `staged` block within `vite.config.ts`. Then, update your lifecycle script so it runs `vp config`. You will also need to create a Vite+ hook at `.vite-hooks/pre-commit` that runs `vp staged`. Finally, once you have confirmed that the Vite+ hook is working as expected, you can remove the old tool's configuration and dependency.
+
+You can find more details about the full Vite+ hook setup in the [Commit hooks guide](/guide/commit-hooks).
+
 ## Examples
 
 ```bash

package/docs/guide/pack.md

@@ -58,4 +58,12 @@ export default defineConfig({
 });
 ```
 
+Executable support is bundled into Vite+, so you do not need to install `@tsdown/exe` separately.
+
+Building executables uses Node's [Single Executable Applications](https://nodejs.org/api/single-executable-applications.html) support and requires Node.js 25.7.0 or later. Switch the active runtime with `vp env use 26` if `vp pack --exe` reports an unsupported version.
+
 See the official [tsdown executable docs](https://tsdown.dev/options/exe#executable) for details about configuring custom file names, embedded assets, and cross-platform targets.
+
+## CSS Bundling
+
+`vp pack` can transform and bundle CSS (including CSS Modules and [Lightning CSS](https://lightningcss.dev/) optimizations) for your entry points. This support is bundled into Vite+, so you do not need to install `@tsdown/css` or `lightningcss` separately, it works out of the box.

package/docs/guide/run.md

@@ -69,7 +69,7 @@ $ node compile-legacy-app.js ✗ cache miss: 'legacy/index.js' modified, executi
 
 ## Task Definitions
 
-Vite Task automatically tracks which files your command uses. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior.
+Vite Task [automatically tracks](/guide/automatic-data-tracking) what each task needs for caching. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior.
 
 ```ts [vite.config.ts]
 import { defineConfig } from 'vite-plus';
@@ -102,10 +102,40 @@ See [Run Config](/config/run) for the full `run` block reference.
 
 ## Task Dependencies
 
-Use [`dependsOn`](#depends-on) to run tasks in the right order. Running `vp run deploy` with the config above runs `build` and `test` first. Dependencies can also target other packages in the same project with the `package#task` notation:
+Use [`dependsOn`](/config/run#dependson) to run tasks in the right order. Running `vp run deploy` with the config above runs `build` and `test` first.
+
+String task names in `dependsOn` reference tasks in the current or another package:
+
+```ts [vite.config.ts]
+dependsOn: [
+  'build', // same package
+  '@my/core#build', // another package
+];
+```
+
+Use the object form when you need to reference all tasks with a given name from the current package's dependencies:
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  run: {
+    tasks: {
+      test: {
+        command: 'vp test',
+        dependsOn: [{ task: 'build', from: 'dependencies' }],
+      },
+    },
+  },
+});
+```
+
+In this example, `vp run test` checks the current package's `dependencies`. For each direct workspace dependency that defines `build`, Vite Task runs that dependency's `build` task before `test`.
+
+Use an array when you need more than one dependency field:
 
 ```ts [vite.config.ts]
-dependsOn: ['@my/core#build', '@my/utils#lint'];
+dependsOn: [{ task: 'build', from: ['dependencies', 'devDependencies'] }];
 ```
 
 ## Running in a Workspace

package/docs/guide/troubleshooting.md

@@ -69,7 +69,7 @@ export default defineConfig({
 
 When `vite.config.ts` imports plugins at the top level, they are evaluated for every command, including `vp lint`, `vp fmt`, editor integrations, and long-lived background processes. This can make config loading slow and may trigger plugin setup side effects, such as reading files, starting watchers, or connecting to services.
 
-Use `lazyPlugins` to load plugins only when the Vite pipeline actually runs (`dev`, `build`, `test`, `preview`):
+Use `lazyPlugins` to skip the plugin factory when vite-plus loads your config only to read a metadata block (`lint`, `fmt`, `check`, `staged`, `pack`, `create`, the `run`/`cache` task lookup, and editor tooling). The plugins still load whenever Vite actually runs, `dev`, `build`, `test`, `preview`, and any build your own scripts spawn (a `vp run` task, `vp exec`):
 
 ```ts [vite.config.ts]
 import { defineConfig, lazyPlugins } from 'vite-plus';

package/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.<sha>` 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.<sha>` 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=<pr-or-sha> bash
 ```
 
-You can verify with `vp outdated` that no Vite+ packages remain outdated.
+On Windows:
 
-### Updating the Vitest Pin
+```powershell
+$env:VP_PR_VERSION = "<pr-or-sha>"
+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.<sha>` 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.<sha>` 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`.

package/docs/package.json

@@ -25,5 +25,5 @@
     "tailwindcss": "^4.1.18",
     "vitepress": "2.0.0-alpha.17"
   },
-  "packageManager": "pnpm@10.33.2"
+  "packageManager": "pnpm@10.34.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plus",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "The Unified Toolchain for the Web",
   "homepage": "https://viteplus.dev/guide",
   "bugs": {
@@ -16,7 +16,8 @@
   "bin": {
     "oxfmt": "./bin/oxfmt",
     "oxlint": "./bin/oxlint",
-    "vp": "./bin/vp"
+    "vp": "./bin/vp",
+    "vpr": "./bin/vpr"
   },
   "files": [
     "AGENTS.md",
@@ -351,7 +352,7 @@
     }
   },
   "dependencies": {
-    "@oxc-project/types": "=0.136.0",
+    "@oxc-project/types": "=0.138.0",
     "@oxlint/plugins": "=1.68.0",
     "@vitest/browser": "4.1.9",
     "@vitest/browser-preview": "4.1.9",
@@ -362,14 +363,14 @@
     "@vitest/snapshot": "4.1.9",
     "@vitest/spy": "4.1.9",
     "@vitest/utils": "4.1.9",
-    "oxfmt": "=0.55.0",
-    "oxlint": "=1.70.0",
-    "oxlint-tsgolint": "=0.23.0",
+    "oxfmt": "=0.57.0",
+    "oxlint": "=1.72.0",
+    "oxlint-tsgolint": "=0.24.0",
     "vitest": "4.1.9",
-    "@voidzero-dev/vite-plus-core": "0.2.1"
+    "@voidzero-dev/vite-plus-core": "0.2.2"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^3.7.1",
+    "@napi-rs/cli": "^3.7.2",
     "@nkzw/safe-word-list": "^3.1.0",
     "@oxc-node/core": "^0.1.0",
     "@types/cross-spawn": "^6.0.6",
@@ -389,15 +390,15 @@
     "mri": "^1.2.0",
     "nanotar": "^0.3.0",
     "picocolors": "^1.1.1",
-    "rolldown-plugin-dts": "^0.25.2",
+    "rolldown-plugin-dts": "^0.26.0",
     "semver": "^7.8.0",
     "tsdown": "^0.22.3",
     "validate-npm-package-name": "^7.0.2",
     "yaml": "^2.8.1",
     "zod": "^3.25.76",
-    "@voidzero-dev/vite-plus-prompts": "0.0.0",
     "@voidzero-dev/vite-plus-tools": "0.0.0",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.1"
+    "@voidzero-dev/vite-plus-prompts": "0.0.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.2"
   },
   "peerDependencies": {
     "@vitest/browser-playwright": "4.1.9",
@@ -429,14 +430,14 @@
     "node": "^20.19.0 || ^22.18.0 || >=24.11.0"
   },
   "optionalDependencies": {
-    "@voidzero-dev/vite-plus-darwin-arm64": "0.2.1",
-    "@voidzero-dev/vite-plus-darwin-x64": "0.2.1",
-    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.2.1",
-    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.2.1",
-    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.2.1",
-    "@voidzero-dev/vite-plus-linux-x64-musl": "0.2.1",
-    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.2.1",
-    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.2.1"
+    "@voidzero-dev/vite-plus-darwin-arm64": "0.2.2",
+    "@voidzero-dev/vite-plus-darwin-x64": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-x64-musl": "0.2.2",
+    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.2.2",
+    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.2.2"
   },
   "scripts": {
     "build": "oxnode -C dev ./build.ts",