vite-plus 0.1.23 → 0.2.0

package/docs/guide/install.md

@@ -9,18 +9,37 @@ Use Vite+ to manage dependencies across pnpm, npm, Yarn, and Bun. Instead of swi
 Vite+ detects the package manager from the workspace root in this order:
 
 1. `packageManager` in `package.json`
-2. `pnpm-workspace.yaml`
-3. `pnpm-lock.yaml`
-4. `yarn.lock` or `.yarnrc.yml`
-5. `package-lock.json`
-6. `bun.lock` or `bun.lockb`
-7. `.pnpmfile.cjs` or `pnpmfile.cjs`
-8. `bunfig.toml`
-9. `yarn.config.cjs`
+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 those files are present, `vp` falls back to `pnpm` by default. Vite+ automatically downloads the matching package manager and uses it for the command you ran. When detection comes from lockfiles or config files, the resolved version is written to `devEngines.packageManager` so future runs are deterministic; projects that already declare `packageManager` or `devEngines.packageManager` are left as-is.
+
+The [`devEngines.packageManager`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines) field accepts a single object or an array of objects, and its `version` may be a semver range:
+
+```json
+{
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "^11.0.0",
+      "onFail": "download"
+    }
+  }
+}
+```
+
+A range resolves to an already-downloaded satisfying version when possible, otherwise to the latest satisfying version from the npm registry. The range itself stays the source of truth; Vite+ never freezes it into an exact `packageManager` pin. When both `packageManager` and `devEngines.packageManager` are declared, the `packageManager` field drives selection and Vite+ warns when it does not satisfy the devEngines constraint (`vp env doctor` shows details).
 
-If none of those files are present, `vp` falls back to `pnpm` by default. Vite+ automatically downloads the matching package manager and uses it for the command you ran.
+Vite+ currently downloads the declared package manager (the `onFail: "download"` behavior); the other `onFail` values are accepted but not yet differentiated.
 
-The explicit `packageManager` field also affects matching package-manager shims. If a project has `packageManager: "npm@10.9.4"`, `npm` and `npx` use npm 10.9.4. Other generated alias pairs behave the same way: `pnpm`/`pnpx`, `yarn`/`yarnpkg`, and `bun`/`bunx`. Mismatched tools are not translated; `npm` in a `pnpm` project still resolves as npm.
+The explicit `packageManager` field (or the `devEngines.packageManager` declaration) also affects matching package-manager shims. If a project has `packageManager: "npm@10.9.4"`, `npm` and `npx` use npm 10.9.4. Other generated alias pairs behave the same way: `pnpm`/`pnpx`, `yarn`/`yarnpkg`, and `bun`/`bunx`. Mismatched tools are not translated; `npm` in a `pnpm` project still resolves as npm.
 
 ## Usage
 
@@ -151,3 +170,20 @@ vp pm config get registry
 vp pm cache clean --force
 vp pm exec tsc --version
 ```
+
+#### Staged publishing
+
+`vp pm stage` exposes [npm's staged publishing](https://docs.npmjs.com/staged-publishing) workflow: a build is uploaded to a staging area (no 2FA, CI-friendly), then a maintainer approves or rejects it from a trusted device (2FA). It adapts to the detected package manager.
+
+```bash
+vp pm stage publish              # upload the package to staging (no 2FA)
+vp pm stage list                 # list staged versions
+vp pm stage view <stage-id>      # inspect a staged version
+vp pm stage download <stage-id>  # download the staged tarball
+vp pm stage approve <stage-id>   # promote to the live registry (2FA)
+vp pm stage reject <stage-id>    # discard a staged version (2FA)
+```
+
+- pnpm (`pnpm stage`, requires pnpm ≥ 11.3) and npm (`npm stage`, requires npm ≥ 11.15 and Node ≥ 22.14) pass through directly.
+- yarn (Berry) uses its npm plugin (`yarn npm publish --staged`, `yarn npm stage …`); `view`/`download` fall back to npm.
+- yarn Classic and bun have no staged-publishing support and fall back to `npm stage`.

package/docs/guide/migrate.md

@@ -75,8 +75,8 @@ Migrate this project to Vite+. Vite+ replaces the current split tooling around r
 After the migration:
 
 - Confirm `vite` imports were rewritten to `vite-plus` where needed
-- Confirm `vitest` imports were rewritten to `vite-plus/test` where needed
-- Remove old `vite` and `vitest` dependencies only after those rewrites are confirmed
+- Confirm `vitest` imports were rewritten to `vite-plus/test` (and `@vitest/browser*` to `vite-plus/test/browser*`) where needed
+- Remove old `vite`, `vitest`, and `@vitest/browser*` dependencies only after those rewrites are confirmed — `vite-plus` ships them as direct deps
 - Move remaining tool-specific config into the appropriate blocks in `vite.config.ts`
 
 Command mapping to keep in mind:
@@ -96,20 +96,30 @@ Summarize the migration at the end and report any manual follow-up still require
 
 ### Vitest
 
-Vitest is automatically migrated through `vp migrate`. If you are migrating manually, you have to update all the imports to `vite-plus/test` instead:
+Vitest is automatically migrated through `vp migrate`. `vite-plus` re-exports upstream `vitest@4.x` under `vite-plus/test*`, so for node-mode tests a single `vite-plus` install is enough — you no longer need to install `vitest` directly.
+
+Browser mode is more nuanced. `vite-plus` bundles the base browser runtime (`@vitest/browser`) and the preview provider (`@vitest/browser-preview`), but the **Playwright** and **WebdriverIO** providers stay opt-in: `@vitest/browser-playwright` (with its `playwright` peer) and `@vitest/browser-webdriverio` (with its `webdriverio` peer) are **not** shipped with `vite-plus`, so non-browser projects never pull them in. `vp migrate` detects the provider you actually use and adds it — pinned to the bundled vitest version — together with its framework. If you migrate manually and use one of these providers, install the provider package and its framework yourself so `vite-plus/test/browser-playwright` / `vite-plus/test/browser-webdriverio` can resolve.
+
+If you are migrating manually, update all the imports to `vite-plus/test*` instead:
 
 ```ts
 // before
+import { defineConfig } from 'vitest/config';
 import { describe, expect, it, vi } from 'vitest';
+import { playwright } from '@vitest/browser-playwright';
 
 const { page } = await import('@vitest/browser/context');
 
 // after
+import { defineConfig } from 'vite-plus';
 import { describe, expect, it, vi } from 'vite-plus/test';
+import { playwright } from 'vite-plus/test/browser-playwright';
 
 const { page } = await import('vite-plus/test/browser/context');
 ```
 
+`declare module 'vitest'` / `declare module '@vitest/browser*'` augmentations are intentionally **not** rewritten — `vite-plus/test*` is a thin re-export of upstream `vitest*`, so type augmentations have to target the upstream module identity to merge correctly. Leave those `declare module` statements pointing at `'vitest'` / `'@vitest/browser*'`.
+
 ### tsdown
 
 If your project uses a `tsdown.config.ts`, move its options into the `pack` block in `vite.config.ts`:

package/docs/guide/troubleshooting.md

@@ -25,37 +25,11 @@ The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`.
 fix before enabling type-aware linting. If that fix fails or is declined, Vite+
 skips `typeAware` and `typeCheck`.
 
-## `vp lint` / `vp fmt` may fail to read `vite.config.ts`
-
-`vp lint`, `vp fmt`, and the Oxc VS Code extension all read the `lint` / `fmt` blocks from `vite.config.ts`. Today that support has important limitations.
-
-### What is currently supported
-
-- Static object export:
-  - `export default { ... }`
-  - `export default defineConfig({ ... })`
-
-### What can fail in current integrations
-
-- Functional or async config:
-  - `defineConfig((env) => ({ ... }))`
-  - `defineConfig(async (env) => ({ ... }))`
-- Config files that rely on Vite transform/bundling behavior to execute.
-
-In scenarios reported in issue #930, Oxc-side integrations that read `vite.config.ts` can behave closer to native ESM loading (similar to Vite `--configLoader native`) than Vite's bundled default loader. That means configs depending on bundling/transforms can fail to load for lint/fmt/editor paths. See: https://github.com/voidzero-dev/vite-plus/issues/930
-
-### Workarounds
-
-- Prefer a static `defineConfig({ ... })` export when you need `lint` / `fmt` in `vite.config.ts`.
-- Avoid Node-specific globals (`__dirname` in ESM), unresolved TS-only imports, or JSON imports without import attributes in config code used by lint/fmt.
-- If needed, keep `.oxlintrc.*` / `.oxfmtrc.*` as temporary fallback, [although we do not recommend doing this normally](/guide/lint##configuration), while this integration behavior is being improved.
-
-### VS Code multi-root workspace note
+## VS Code extension does not read `vite.config.ts`
 
 If VS Code has multiple folders open, the shared Oxc language server may pick a different workspace than expected. That can make it look like `vite.config.ts` support is missing.
 
 - Confirm the extension is using the intended workspace.
-- Confirm the workspace resolves to a recent Oxc/Oxlint/Oxfmt toolchain.
 
 ## `vp build` does not run my build script
 
@@ -93,9 +67,9 @@ export default defineConfig({
 
 ## Slow config loading caused by heavy plugins
 
-When `vite.config.ts` imports heavy plugins at the top level, every `import` is evaluated eagerly, even for commands like `vp lint` or `vp fmt` that don't need those plugins. This can make config loading noticeably slow.
+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 wrap plugin loading. Plugins are only loaded for commands that need them (`dev`, `build`, `test`, `preview`), and skipped for everything else:
+Use `lazyPlugins` to load plugins only when the Vite pipeline actually runs (`dev`, `build`, `test`, `preview`):
 
 ```ts [vite.config.ts]
 import { defineConfig, lazyPlugins } from 'vite-plus';

package/docs/guide/upgrade.md

@@ -14,9 +14,22 @@ You can upgrade both of them independently.
 ## Global `vp`
 
 ```bash
-vp upgrade
+vp upgrade                        # upgrade to the latest version
+vp upgrade --check                # check for updates without installing
+vp upgrade <version>              # install a specific version
+vp upgrade --registry <registry>  # use a custom npm registry
 ```
 
+### Rollback
+
+Vite+ keeps the **3 most recent** versions installed so you can revert quickly:
+
+```bash
+vp upgrade --rollback
+```
+
+Older versions are pruned automatically after each upgrade. The active version and the previous version are always kept, so a rollback target is never removed.
+
 ## Local `vite-plus`
 
 Update the project dependency with the package manager commands in Vite+:
@@ -29,21 +42,38 @@ You can also use `vp add vite-plus@latest` if you want to move the dependency ex
 
 ### Updating Aliased Packages
 
-Vite+ sets up npm aliases for its core packages during installation:
+Vite+ sets up an npm alias for its core package during installation:
 
 - `vite` is aliased to `npm:@voidzero-dev/vite-plus-core@latest`
-- `vitest` is aliased to `npm:@voidzero-dev/vite-plus-test@latest`
 
-`vp update vite-plus` does not re-resolve these aliases in the lockfile. To fully upgrade, update them separately:
+`vp update vite-plus` does not re-resolve this alias in the lockfile. To fully upgrade, update it separately:
 
 ```bash
-vp update @voidzero-dev/vite-plus-core @voidzero-dev/vite-plus-test
+vp update @voidzero-dev/vite-plus-core
 ```
 
 Or update everything at once:
 
 ```bash
-vp update vite-plus @voidzero-dev/vite-plus-core @voidzero-dev/vite-plus-test
+vp update vite-plus @voidzero-dev/vite-plus-core
 ```
 
 You can verify with `vp outdated` that no Vite+ packages remain outdated.
+
+### 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:
+
+- **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.
+
+After upgrading `vite-plus`, re-pin `vitest` to the version Vite+ now bundles. Check that version with:
+
+```bash
+vp --version
+```
+
+Then set the `vitest` override to that exact version, or rerun `vp migrate` to update the pin for you.

package/docs/package.json

@@ -17,13 +17,13 @@
     "vitepress-plugin-llms": "^1.12.2",
     "vitepress-plugin-mermaid": "^2.0.17",
     "vue": "^3.5.27",
-    "vue3-carousel": "^0.16.0"
+    "vue3-carousel": "^0.17.0"
   },
   "devDependencies": {
-    "@voidzero-dev/vitepress-theme": "4.8.3",
+    "@voidzero-dev/vitepress-theme": "4.8.4",
     "oxc-minify": "^0.120.0",
     "tailwindcss": "^4.1.18",
-    "vitepress": "2.0.0-alpha.15"
+    "vitepress": "2.0.0-alpha.17"
   },
   "packageManager": "pnpm@10.33.2"
 }