vite-plus 0.3.2 → 1.0.0-rc.0

package/docs/guide/index.md

@@ -1,14 +1,20 @@
 # Getting Started
 
-Vite+ is the unified toolchain and entry point for web development. It manages your runtime, package manager, and frontend toolchain in one place by combining [Vite](https://vite.dev/), [Vitest](https://vitest.dev/), [Oxlint](https://oxc.rs/docs/guide/usage/linter.html), [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html), [Rolldown](https://rolldown.rs/), [tsdown](https://tsdown.dev/), and [Vite Task](https://github.com/voidzero-dev/vite-task).
+Vite+ is the unified toolchain and entry point for web development.
 
-Vite+ ships in two parts: `vp`, the global command-line tool, and `vite-plus`, the local package installed in each project. If you already have a Vite project, use [`vp migrate`](/guide/migrate) to migrate it to Vite+, or paste our [migration prompt](/guide/migrate#migration-prompt) into your coding agent.
+It brings together [Vite](https://vite.dev/), [Vitest](https://vitest.dev/), [Oxlint](https://oxc.rs/docs/guide/usage/linter.html), [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html), [Rolldown](https://rolldown.rs/), [tsdown](https://tsdown.dev/), and [Vite Task](https://github.com/voidzero-dev/vite-task) in a single [`vite-plus` package](/guide/local-cli) for a blazing fast frontend toolchain.
 
-Building with an AI assistant? View and copy a ready-made setup prompt:
+Vite+ also ships a [global `vp` CLI](/guide/global-cli) that manages Node.js and package managers and makes Vite+ easier to use across projects. You can use either CLI independently, but we recommend [using them together](/guide/global-cli#use-both-clis-together).
+
+If you already have a Vite project, run [`vp migrate`](/guide/migrate) to migrate it to Vite+, or give your coding agent our [migration prompt](/guide/migrate#migration-prompt).
+
+Building with an AI assistant? View and copy a prompt to create a new project, migrate an existing project, or upgrade Vite+:
 
 <CopyPrompt />
 
-## Install `vp`
+## Install `vp` Globally
+
+The commands below install the global `vp` CLI, which manages Node.js and package managers and makes `vp` available across projects. If you only need the frontend toolchain in a single project, you can install the [project-local CLI](/guide/local-cli#install) instead.
 
 ### macOS / Linux
 
@@ -28,7 +34,9 @@ Alternatively, download and run [`vp-setup.exe`](https://setup.viteplus.dev).
 The `vp-setup.exe` is not yet code-signed. Your browser may show a warning when downloading. Click **"..."** → **"Keep"** → **"Keep anyway"** to proceed. If Windows Defender SmartScreen blocks the file when you run it, click **"More info"** → **"Run anyway"**.
 :::
 
-The installer scripts and `vp-setup.exe` read [environment variables](/guide/installer-env-vars) such as `VP_VERSION` and `VP_HOME`.
+The installer scripts and `vp-setup.exe` read [environment variables](/guide/global-cli#installation-variables) such as `VP_VERSION` and `VP_HOME`.
+
+If you use Nushell with custom XDG directories, read the [Nushell startup requirements](/guide/global-cli#nushell-and-xdg-directories) before installing.
 
 After installation, open a new shell and run:
 
@@ -71,7 +79,7 @@ This is required because the managed [unofficial-builds](https://unofficial-buil
 
 ## Quick Start
 
-Create a project, install dependencies, and use the default commands:
+With the global CLI installed, create a project, install dependencies, and use the default commands:
 
 ```bash
 vp create # Create a new project
@@ -82,54 +90,49 @@ vp test # Run JavaScript tests
 vp build # Build for production
 ```
 
-You can also just run `vp` on its own and use the interactive command line.
+You can also run `vp` on its own to open the interactive command line. In a local-only setup, run the same commands through your package manager, such as `pnpm exec vp check`.
 
 ## Core Commands
 
-Vite+ can handle the entire local frontend development cycle from starting a project, developing it, checking & testing, and building it for production.
+Vite+ covers the full frontend development cycle, from starting a project through development, checks, tests, and production builds. Most commands are available from both distributions; machine-level environment and self-management commands require the global CLI.
 
-### Start
+### Set Up a Project
 
 - [`vp create`](/guide/create) creates new apps, packages, and monorepos.
 - [`vp migrate`](/guide/migrate) moves existing projects onto Vite+.
-- [`vp config`](/guide/commit-hooks) installs the Git hook dispatcher and configures agent integration.
-- [`vp hooks`](/guide/commit-hooks) manages the Git hook dispatcher (`enable`, `disable`, `status`).
-- [`vp staged`](/guide/commit-hooks) runs checks on staged files.
 - [`vp install`](/guide/install) installs dependencies with the right package manager.
-- [`vp env`](/guide/env) manages Node.js and package-manager environments.
+- [`vp add`](/guide/install), [`vp remove`](/guide/install), [`vp update`](/guide/install), [`vp dedupe`](/guide/install), [`vp outdated`](/guide/install), [`vp list`](/guide/install), [`vp why`](/guide/install), and [`vp info`](/guide/install) cover the rest of the package-management workflow.
+- [`vp link`](/guide/install), [`vp unlink`](/guide/install), [`vp rebuild`](/guide/install), and [`vp pm <command>`](/guide/install) provide lower-level package-manager operations.
 
-### Develop
+### Project Toolchain
 
-- [`vp dev`](/guide/dev) starts the dev server powered by Vite.
 - [`vp check`](/guide/check) runs format, lint, and type checks together.
-- [`vp lint`](/guide/lint), [`vp fmt`](/guide/fmt), and [`vp test`](/guide/test) let you run those tools directly.
-
-### Execute
-
+- [`vp lint`](/guide/lint) and [`vp fmt`](/guide/fmt) run the individual checks directly.
+- [`vp test`](/guide/test) runs tests with Vitest.
+- [`vp dev`](/guide/dev) starts the development server powered by Vite.
+- [`vp build`](/guide/build) builds apps, and [`vp preview`](/guide/build) previews the production build locally.
+- [`vp pack`](/guide/pack) builds libraries or standalone artifacts.
+- [`vp toolchain`](/guide/upgrade#show-the-toolchain) shows the active project toolchain; use `--global` to inspect the global installation instead.
 - [`vp run`](/guide/run) runs tasks across workspaces with caching.
-- [`vp exec`](/guide/vpx) runs local project binaries.
-- [`vp node`](/guide/env) runs Node.js scripts with the resolved Vite+ environment.
-- [`vp dlx`](/guide/vpx) downloads and runs package binaries without adding them as dependencies.
 - [`vp cache clean`](/guide/cache) clears task cache entries.
-- [`vpx`](/guide/vpx) downloads and runs binaries globally.
+- [`vp exec`](/guide/vpx) runs local project binaries, while [`vp dlx`](/guide/vpx) and [`vpx`](/guide/vpx) download and run package binaries.
+- [`vp config`](/guide/commit-hooks) installs the Git hook dispatcher and configures agent integration.
+- [`vp hooks`](/guide/commit-hooks) manages the Git hook dispatcher, and [`vp staged`](/guide/commit-hooks) runs checks on staged files.
+- [Monorepo Guide](/guide/monorepo) covers multi-package project structure and commands.
 
-### Build
+### Global CLI
 
-- [`vp build`](/guide/build) builds apps.
-- [`vp pack`](/guide/pack) builds libraries or standalone artifacts.
-- [`vp preview`](/guide/build) previews the production build locally.
+- [`vp env`](/guide/env) manages Node.js and package-manager environments, and [`vp node`](/guide/env) runs scripts with the resolved environment.
+- [`vp upgrade`](/guide/upgrade) updates the global `vp` installation itself.
+- [`vp implode`](/guide/implode) removes the global `vp` installation and related Vite+ data from your machine.
 
-### Manage Dependencies
+### Workflow
 
-- [`vp add`](/guide/install), [`vp remove`](/guide/install), [`vp update`](/guide/install), [`vp dedupe`](/guide/install), [`vp outdated`](/guide/install), [`vp list`](/guide/install), [`vp why`](/guide/install), and [`vp info`](/guide/install) wrap package-manager workflows.
-- [`vp link`](/guide/install), [`vp unlink`](/guide/install), and [`vp rebuild`](/guide/install) cover local package links and native module rebuilds.
-- [`vp pm <command>`](/guide/install) calls other package manager commands directly.
+- [IDE Integration](/guide/ide-integration), [CI](/guide/ci), and [Docker](/guide/docker) cover common development and deployment environments.
 
-### Maintain
+### Reference
 
-- [`vp toolchain`](/guide/upgrade#show-the-toolchain) shows the versions and relationships in the active Vite+ toolchain.
-- [`vp upgrade`](/guide/upgrade) updates the `vp` installation itself.
-- [`vp implode`](/guide/implode) removes `vp` and related Vite+ data from your machine.
+- [Troubleshooting](/guide/troubleshooting) covers common command, configuration, and integration problems.
 
 ::: info
 Vite+ ships with many predefined commands such as `vp build`, `vp test`, and `vp dev`. These commands are built-in and cannot be changed. If you want to run a command from your `package.json` scripts, use `vp run <command>` or `vpr <command>`.

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,14 +39,7 @@ 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.
+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 aliases behave the same way: `pnpm`/`pnpx`/`pn`/`pnx`, `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

@@ -20,7 +20,9 @@ vp lint --type-aware
 
 Put lint configuration directly in the `lint` block in the root `vite.config.ts` so all your configuration stays in one place. We do not recommend using `oxlint.config.ts` or `.oxlintrc.json` with Vite+.
 
-Vite+ does not currently support nested lint configuration. For now, use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) in the root `vite.config.ts` for file- or package-specific rules. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
+When the workspace-root config has a `lint` block, `vp lint` and `vp check` use it even when run from a package directory. Package configs cannot replace the root rules or disable its `typeAware` and `typeCheck` options. Commands keep the package working directory, so relative file arguments retain their meaning. Use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) for file- or package-specific rules.
+
+An explicit `vp lint -c <path>` or `vp lint --config <path>` selects another config. Otherwise, when running from the workspace root or when the root config has no `lint` block, Oxlint discovers the nearest `vite.config.*` file with a `lint` block. Supported extensions are `.js`, `.mjs`, `.ts`, `.cjs`, `.mts`, and `.cts`. Nested configs do not override settings for individual files.
 
 For the upstream rule set, options, and compatibility details, see the [Oxlint docs](https://oxc.rs/docs/guide/usage/linter.html).
 
@@ -96,14 +98,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: 5.0.1
+```
+
+```json [npm / Bun package.json]
+"overrides": {
+  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+  "vitest": "5.0.1"
+}
+```
+
+```json [Yarn package.json]
+"resolutions": {
+  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+  "vitest": "5.0.1"
+}
+```
+
+:::
+
+::: 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.