vite-plus 0.3.2 → 0.3.3

package/docs/guide/install.md

@@ -1,6 +1,6 @@
-# Installing Dependencies
+# Package Management
 
-`vp install` installs dependencies using the current workspace's package manager.
+`vp` detects and runs the current workspace's package manager. These commands are available from both the [global CLI](/guide/global-cli) and the [project-local CLI](/guide/local-cli).
 
 ## Overview
 
@@ -21,8 +21,6 @@ Vite+ detects the package manager from the workspace root in this order:
 
 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, but package-manager detection never rewrites `package.json`. Use `vp env pin <package-manager>@<version>` when the project should declare an exact version explicitly.
 
-After selecting the package manager, Vite+ forwards the command without separately validating whether `package.json` exists. Missing-manifest behavior therefore matches the selected package manager.
-
 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
@@ -41,13 +39,6 @@ A range resolves to an already-downloaded satisfying version when possible, othe
 
 Vite+ currently downloads the declared package manager (the `onFail: "download"` behavior); the other `onFail` values are accepted but not yet differentiated.
 
-A `packageManager` pin can carry an integrity hash (`yarn@4.17.1+sha512.…`). `corepack use` writes that hash. Vite+ hashes the same artifact as Corepack:
-
-- the extracted CLI binary (`bin/yarn.js`) for Yarn 2 and later
-- the npm package tarball for npm, pnpm, and Yarn Classic
-
-Vite+ hashes the CLI once, when it installs Yarn, and records the pin it verified. A later command compares its own pin against that record. A pin that does not match the record fails the check, and the command stops. Corepack keeps the same kind of record for its own cache.
-
 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
@@ -83,8 +74,7 @@ Updates keep the version spec a package was installed with: a package installed
 ::: warning
 These commands do **NOT** interact with the underlying package manager's global installation directory.
 
-Instead, Vite+ stores its global packages in `packages/` under the resolved data
-directory. These packages remain available across different Node.js versions.
+Instead, Vite+ stores its global packages in `packages/` under the resolved data directory. These packages remain available across different Node.js versions.
 
 As a result, commands such as `vp link` do not affect Vite+'s global packages and will not appear in `vp list -g`.
 :::
@@ -122,6 +112,10 @@ Use `vp install` when you want to install exactly what the current `package.json
 - `vp install --filter <pattern>` scopes install work in monorepos
 - `vp install -w` installs in the workspace root
 
+##### Git and remote tarball dependencies (npm v12+)
+
+npm v12 stops resolving git dependencies (`github:`, `git+https:`) and remote tarball URLs by default; such installs fail with `EALLOWGIT` / `EALLOWREMOTE`. Opt back in per project with npm's `allow-git` / `allow-remote` config.
+
 #### Global Install
 
 Use these commands when you want package-manager-managed tools available outside a single project.
@@ -160,10 +154,7 @@ Use these when you need to understand the current state of dependencies.
 - `vp why react` explains why `react` is installed
 - `vp info react` shows registry metadata such as versions and dist-tags
 
-These commands show the packages that the package manager installed. They do
-not show tools that Vite+ bundles or compiles. Run `vp toolchain [tool]` to show
-these tools, including Vite, Rolldown, and Oxc. For readable output, `vp why`
-shows a hint when Vite+ also provides the package.
+These commands show the packages that the package manager installed. They do not show tools that Vite+ bundles or compiles. Run `vp toolchain [tool]` to show these tools, including Vite, Rolldown, and Oxc. For readable output, `vp why` shows a hint when Vite+ also provides the package.
 
 #### Rebuild
 
@@ -194,8 +185,6 @@ npm v12 skips dependency install scripts (`preinstall` / `install` / `postinstal
 
 Approval only records the allowlist: scripts an earlier install skipped do not run until you run `vp rebuild <pkg>`. With npm 11.16 - 11.x the same commands work, but npm treats the allowlist as advisory and still runs scripts.
 
-npm v12 also stops resolving git dependencies (`github:`, `git+https:`) and remote tarball URLs by default; such installs fail with `EALLOWGIT` / `EALLOWREMOTE`. Opt back in per project with npm's `allow-git` / `allow-remote` config.
-
 #### Advanced
 
 Use these when you need lower-level package-manager behavior.
@@ -228,3 +217,12 @@ 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-Manager Integrity Verification
+
+A `packageManager` pin can carry an integrity hash (`yarn@4.17.1+sha512.…`). `corepack use` writes that hash. Vite+ hashes the same artifact as Corepack:
+
+- the extracted CLI binary (`bin/yarn.js`) for Yarn 2 and later
+- the npm package tarball for npm, pnpm, and Yarn Classic
+
+Vite+ hashes the CLI once, when it installs Yarn, and records the pin it verified. A later command compares its own pin against that record. A pin that does not match the record fails the check, and the command stops. Corepack keeps the same kind of record for its own cache.

package/docs/guide/lint.md

@@ -96,14 +96,8 @@ export default defineConfig({
 
 For rule tests, `RuleTester` is available from `vite-plus/lint/plugins-dev`.
 
-Both entrypoints re-export the copy that ships with Vite+. The API therefore
-always matches the bundled Oxlint.
+Both entrypoints re-export the copy that ships with Vite+. The API therefore always matches the bundled Oxlint.
 
-Use them instead of adding `@oxlint/plugins` or `oxlint` as a direct
-dependency. A separately pinned copy can drift from the linter that loads your
-plugin. It also does not resolve from a plugin file under pnpm's strict layout,
-unless every package that holds a plugin declares it.
+Use them instead of adding `@oxlint/plugins` or `oxlint` as a direct dependency. A separately pinned copy can drift from the linter that loads your plugin. It also does not resolve from a plugin file under pnpm's strict layout, unless every package that holds a plugin declares it.
 
-`vp migrate` rewrites existing `oxlint` and `@oxlint/plugins` imports for you.
-See [Oxlint JS Plugin Imports](/guide/migrate-rules#oxlint-js-plugin-imports).
-The `vite-plus/prefer-vite-plus-imports` rule reports any that come back.
+`vp migrate` rewrites existing `oxlint` and `@oxlint/plugins` imports for you. See [Oxlint JS Plugin Imports](/guide/migrate-rules#oxlint-js-plugin-imports). The `vite-plus/prefer-vite-plus-imports` rule reports any that come back.

package/docs/guide/local-cli.md

@@ -0,0 +1,123 @@
+# Project-local CLI
+
+Different from [global `vp` cli](/guide/global-cli), the `vite-plus` is a npm package which contains the project-local `vp` CLI and the integrated frontend toolchain. Install it as a development dependency when you want the toolchain version recorded in the project's manifest and lockfile, or when you do not want to install the standalone global CLI.
+
+The local package includes Vite, Rolldown, Vitest, Oxlint, Oxfmt, tsdown, the Vite+ task runner, and package-manager commands. It requires an existing Node.js runtime and package manager.
+
+## Install
+
+For most of use cases, we recommend to use Vite+ cli to install in a project or create a new project. Learn more in [Creating a Project](/guide/create) and [Migrate to Vite+](/guide/migrate).
+
+::: code-group
+
+```bash [pnpm]
+pnpm dlx --package=vite-plus vp create
+```
+
+```bash [npm]
+npx --package=vite-plus vp create
+```
+
+```bash [Yarn]
+yarn dlx --package vite-plus vp create
+```
+
+```bash [Bun]
+bunx --package vite-plus vp create
+```
+
+:::
+
+Run its binary through your package manager. For example:
+
+```bash
+./node_modules/.bin/vp migrate --help
+./node_modules/.bin/vp check
+```
+
+The documentation uses bare `vp` commands for readability. Without the global CLI, prefix interactive commands with your package manager's local-binary executor, such as `pnpm exec`.
+
+### Manual Installation
+
+If you are manually migrating a project to Vite+, install these dev dependencies first:
+
+```bash
+vp install -D vite-plus
+```
+
+You need to add overrides to your package manager so that other packages resolve the Vite+ versions: alias `vite` to `@voidzero-dev/vite-plus-core`, and pin `vitest` to the version Vite+ bundles (run `vp --version`) so the whole project shares a single Vitest copy with `vp test`. Without the `vitest` pin, a dependency or workspace package can pull a different Vitest than the bundled runner, splitting Vitest's internals (mocks, `expect`, runner state):
+
+::: code-group
+
+```yaml [pnpm-workspace.yaml]
+overrides:
+  vite: npm:@voidzero-dev/vite-plus-core@latest
+  vitest: 4.1.11
+```
+
+```json [npm / Bun package.json]
+"overrides": {
+  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+  "vitest": "4.1.11"
+}
+```
+
+```json [Yarn package.json]
+"resolutions": {
+  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+  "vitest": "4.1.11"
+}
+```
+
+:::
+
+::: details Why are these settings needed?
+
+Dependencies and plugins can import `vite` or `vitest` directly, even when your own code imports from `vite-plus`. These overrides align their dependencies with the toolchain Vite+ uses:
+
+- The `vite` alias directs those imports to Vite+'s core package. Separate Vite instances can break runtime identity checks: [issue #1391](https://github.com/voidzero-dev/vite-plus/issues/1391) reported TanStack Start returning 404s because an `instanceof` check crossed two copies. [PR #2617](https://github.com/voidzero-dev/vite-plus/pull/2617) addresses the CLI side by sharing Vite through the same alias.
+- The exact `vitest` pin keeps dependencies and `vp test` on the same Vitest version, avoiding separate mocks, `expect` instances, and runner state. [PR #2365](https://github.com/voidzero-dev/vite-plus/pull/2365) documents this requirement for manual installation.
+
+Keep the core alias aligned with your installed `vite-plus` version and update the Vitest pin to match its bundled version when upgrading. [Issue #2356](https://github.com/voidzero-dev/vite-plus/issues/2356) describes how dependency bots can update these packages independently and leave incompatible versions installed together.
+
+:::
+
+## Best Practices
+
+We recommend using the [global CLI](/guide/global-cli) together with the project-local CLI. The global CLI makes `vp` available directly in your terminal and delegates development commands such as `vp dev`, `vp build`, and `vp test` to the project's installed `vite-plus` package. This gives you convenient access to the toolchain while keeping its version controlled by the project. You can also use only the project-local CLI if you prefer.
+
+For open-source projects or any project with collaborators, we recommend adding `package.json` scripts that call `vp`, whether you use both CLIs or only the project-local CLI. Inside scripts, `vp` resolves automatically from `node_modules/.bin`:
+
+```json [package.json]
+{
+  "scripts": {
+    "dev": "vp dev",
+    "check": "vp check",
+    "test": "vp test",
+    "build": "vp build"
+  }
+}
+```
+
+After installing the project's dependencies, contributors can run these scripts through their package manager, such as `pnpm run dev` or `npm run dev`, without being required to install the global CLI.
+
+## What It Includes
+
+The project-local CLI can be used independently for:
+
+- [`vp dev`](/guide/dev), [`vp build`](/guide/build), and [`vp preview`](/guide/build) with Vite and Rolldown
+- [`vp check`](/guide/check), [`vp lint`](/guide/lint), and [`vp fmt`](/guide/fmt) with Oxc
+- [`vp test`](/guide/test) with Vitest
+- [`vp pack`](/guide/pack) with tsdown
+- [`vp toolchain`](/guide/upgrade#show-the-toolchain) for inspecting the versions bundled with the project-local package
+- [`vp run`](/guide/run) and task caching across workspaces
+- [package-manager commands](/guide/install) using the Node.js runtime already active in your shell
+- [`vp create`](/guide/create), [`vp migrate`](/guide/migrate), and project configuration commands
+
+The local package cannot manage the machine-level Vite+ installation. The `vp env`, `vp upgrade`, and `vp implode` commands require the [global CLI](/guide/global-cli). Upgrade or remove a local-only installation through your package manager.
+
+## Add the Global CLI Later
+
+You can install the global CLI at any time without changing the project's dependency. Commands such as `vp dev`, `vp build`, and `vp test` will continue to use the project's installed `vite-plus` version.
+
+See [Use Both CLIs Together](/guide/global-cli#use-both-clis-together) for the selection rules.