diff --git a/.claude/skills/sync-upstream-dependency-docs/SKILL.md b/.claude/skills/sync-upstream-dependency-docs/SKILL.md index 52a9ce9cbf..86f9c80fb4 100644 --- a/.claude/skills/sync-upstream-dependency-docs/SKILL.md +++ b/.claude/skills/sync-upstream-dependency-docs/SKILL.md @@ -12,9 +12,10 @@ allowed-tools: Read, Grep, Glob, Edit, Bash package name and its old exact version. Do not treat changelogs, RFC examples, snapshots, or broad ranges such as `vitest@4.x` as current-version references. 3. Update references that promise to match Vite+'s currently bundled version. In - particular, keep every exact Vitest pin in the manual-migration examples in sync, - including `docs/guide/migrate.md`, `README.md`, and `packages/cli/README.md` when - those examples are present. + particular, keep every exact Vitest pin in the manual-installation examples in + `docs/guide/local-cli.md`, `README.md`, and `packages/cli/README.md` in sync. + Project-local upgrade guidance lives in `docs/guide/upgrade-project.md`; + `docs/guide/upgrade.md` covers global CLI upgrades. 4. Preserve the surrounding wording and formatting. Do not rewrite examples whose version is intentionally historical or illustrative. 5. Re-run the searches for the changed packages and inspect the focused diff. No diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 293673f43f..9ae1d27eff 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -27,46 +27,32 @@ function rewriteInstallUrls(text: string): string { .replaceAll('https://vite.plus', installShUrl); } -const taskRunnerGuideItems = [ - { - text: 'Run', - link: '/guide/run', - }, +const guideSidebar = [ { - text: 'Task Caching', - link: '/guide/cache', + text: 'Introduction', items: [ - { text: 'Automatic Data Tracking', link: '/guide/automatic-data-tracking' }, - { text: 'GitHub Actions Cache', link: '/guide/github-actions-cache' }, + { text: 'Getting Started', link: '/guide/' }, + { text: 'Global CLI', link: '/guide/global-cli' }, + { text: 'Project-local CLI', link: '/guide/local-cli' }, + { text: 'Why Vite+', link: '/guide/why' }, ], }, { - text: 'Running Binaries', - link: '/guide/vpx', - }, -]; - -const guideSidebar = [ - { - text: 'Introduction', + text: 'Set Up a Project', items: [ - { text: 'Getting Started', link: '/guide/' }, { text: 'Creating a Project', link: '/guide/create' }, { text: 'Migrate to Vite+', link: '/guide/migrate', items: [{ text: 'Migration Rules', link: '/guide/migrate-rules' }], }, - { text: 'Installing Dependencies', link: '/guide/install' }, - { text: 'Environment', link: '/guide/env' }, - { text: 'Installer Environment Variables', link: '/guide/installer-env-vars' }, - { text: 'Why Vite+', link: '/guide/why' }, + { text: 'Update Vite+', link: '/guide/upgrade-project' }, + { text: 'Package Management', link: '/guide/install' }, ], }, { - text: 'Develop', + text: 'Project Toolchain', items: [ - { text: 'Dev', link: '/guide/dev' }, { text: 'Check', link: '/guide/check', @@ -76,22 +62,33 @@ const guideSidebar = [ ], }, { text: 'Test', link: '/guide/test' }, - ], - }, - { - text: 'Execute', - items: taskRunnerGuideItems, - }, - { - text: 'Build', - items: [ + { text: 'Dev', link: '/guide/dev' }, { text: 'Build', link: '/guide/build' }, { text: 'Pack', link: '/guide/pack' }, + { + text: 'Run', + link: '/guide/run', + }, + { + text: 'Task Caching', + link: '/guide/cache', + items: [ + { text: 'Automatic Data Tracking', link: '/guide/automatic-data-tracking' }, + { text: 'GitHub Actions Cache', link: '/guide/github-actions-cache' }, + ], + }, + { + text: 'Running Binaries', + link: '/guide/vpx', + }, + { text: 'Commit Hooks', link: '/guide/commit-hooks' }, + { text: 'Monorepo Guide', link: '/guide/monorepo' }, ], }, { - text: 'Maintain', + text: 'Global CLI', items: [ + { text: 'Environment', link: '/guide/env' }, { text: 'Upgrading Vite+', link: '/guide/upgrade' }, { text: 'Removing Vite+', link: '/guide/implode' }, ], @@ -102,11 +99,12 @@ const guideSidebar = [ { text: 'IDE Integration', link: '/guide/ide-integration' }, { text: 'CI', link: '/guide/ci' }, { text: 'Docker', link: '/guide/docker' }, - { text: 'Commit Hooks', link: '/guide/commit-hooks' }, - { text: 'Monorepo Guide', link: '/guide/monorepo' }, - { text: 'Troubleshooting', link: '/guide/troubleshooting' }, ], }, + { + text: 'Reference', + items: [{ text: 'Troubleshooting', link: '/guide/troubleshooting' }], + }, ]; export default extendConfig( diff --git a/docs/config/staged.md b/docs/config/staged.md index 07e506b6d6..11393c798c 100644 --- a/docs/config/staged.md +++ b/docs/config/staged.md @@ -1,7 +1,6 @@ # Staged Config -`vp staged` reads staged-file rules from the `staged` block in `vite.config.ts`. See the -[Commit hooks guide](/guide/commit-hooks). +`vp staged` reads staged-file rules from the `staged` block in `vite.config.ts`. See the [Commit hooks guide](/guide/commit-hooks). ## Example diff --git a/docs/guide/ci.md b/docs/guide/ci.md index 00c103a5b1..83dfdba2e0 100644 --- a/docs/guide/ci.md +++ b/docs/guide/ci.md @@ -10,37 +10,7 @@ You can use `voidzero-dev/setup-vp` to use Vite+ in CI environments. Set `` in each example to an exact version from the [`setup-vp` releases page](https://github.com/voidzero-dev/setup-vp/releases). You can use a commit SHA instead. Do not use the `v1` tag. The `v1` tag no longer receives updates. -Run `vp migrate` to replace exact `voidzero-dev/setup-vp@v1` references in -GitHub Actions workflows and composite actions under `.github` with the latest -exact release known to your Vite+ version. Existing exact versions and commit -SHAs remain unchanged. - -### Automatic Version Updates - -Dependabot and Renovate can update exact versions in GitHub Actions workflows. - -To use [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates), add a `github-actions` entry to `.github/dependabot.yml`: - -```yaml [.github/dependabot.yml] -version: 2 -updates: - - package-ecosystem: github-actions - directory: / - schedule: - interval: weekly -``` - -Dependabot checks `uses:` entries in `.github/workflows` each week. - -[Renovate's GitHub Actions manager](https://docs.renovatebot.com/modules/manager/github-actions/) detects `uses:` entries by default. You do not need a package rule for `setup-vp`. - -When you use a commit SHA, add the exact release tag in a comment. Renovate uses the comment to find updates: - -```yaml -- uses: voidzero-dev/setup-vp@ # -``` - -These settings apply only to GitHub Actions workflows. For GitLab CI/CD and Azure Pipelines, update both version values together. +Run `vp migrate` to replace exact `voidzero-dev/setup-vp@v1` references in GitHub Actions workflows and composite actions under `.github` with the latest exact release known to your Vite+ version. Existing exact versions and commit SHAs remain unchanged. ## GitHub Actions @@ -125,6 +95,33 @@ The Azure Pipelines template supports Microsoft-hosted Linux, macOS, and Windows For advanced configuration and the complete parameter reference, see the [`setup-vp` Azure Pipelines documentation](https://github.com/voidzero-dev/setup-vp#azure-pipelines). +## Automatic Version Updates + +Dependabot and Renovate can update exact versions in GitHub Actions workflows. + +To use [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates), add a `github-actions` entry to `.github/dependabot.yml`: + +```yaml [.github/dependabot.yml] +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly +``` + +Dependabot checks `uses:` entries in `.github/workflows` each week. + +[Renovate's GitHub Actions manager](https://docs.renovatebot.com/modules/manager/github-actions/) detects `uses:` entries by default. You do not need a package rule for `setup-vp`. + +When you use a commit SHA, add the exact release tag in a comment. Renovate uses the comment to find updates: + +```yaml +- uses: voidzero-dev/setup-vp@ # +``` + +These settings apply only to GitHub Actions workflows. For GitLab CI/CD and Azure Pipelines, update both version values together. + ## Simplifying Existing Workflows If you are migrating an existing GitHub Actions workflow, you can often replace large blocks of Node, package-manager, and cache setup with a single `setup-vp` step. diff --git a/docs/guide/commit-hooks.md b/docs/guide/commit-hooks.md index 36d4584d0a..96a5480bc2 100644 --- a/docs/guide/commit-hooks.md +++ b/docs/guide/commit-hooks.md @@ -1,7 +1,6 @@ # Commit Hooks -Use `vp hooks` to manage the Git hook dispatcher, `vp config` for project setup -(hooks + agent integration), and `vp staged` to run checks on staged files. +Use `vp hooks` to manage the Git hook dispatcher, `vp config` for project setup (hooks + agent integration), and `vp staged` to run checks on staged files. ## Overview @@ -64,10 +63,7 @@ Check the `Dispatcher` and `core.hooksPath` lines to see whether hooks are actua ### `vp config` -`vp config` configures Vite+ for the current project. It installs the generated Git hook -dispatcher (unless hooks were disabled with `vp hooks disable`) and can also handle related -project integration such as agent setup. The hooks directory defaults to `.vite-hooks`, or the -last directory used by `vp hooks` / `vp config` in this clone: +`vp config` configures Vite+ for the current project. It installs the generated Git hook dispatcher (unless hooks were disabled with `vp hooks disable`) and can also handle related project integration such as agent setup. The hooks directory defaults to `.vite-hooks`, or the last directory used by `vp hooks` / `vp config` in this clone: ```bash vp config @@ -76,24 +72,15 @@ vp config --no-hooks vp config --no-agent ``` -Use `--no-hooks` when you want `vp config` to leave the Git hook dispatcher unchanged. Use -`--no-agent` when you want it to skip updates to existing coding agent instruction files. You can -pass both flags when you want `vp config` to skip both setup steps. After `vp hooks disable`, -`vp config` skips reinstalling the dispatcher and points you at `vp hooks enable` instead of -prompting again. +Use `--no-hooks` when you want `vp config` to leave the Git hook dispatcher unchanged. Use `--no-agent` when you want it to skip updates to existing coding agent instruction files. You can pass both flags when you want `vp config` to skip both setup steps. After `vp hooks disable`, `vp config` skips reinstalling the dispatcher and points you at `vp hooks enable` instead of prompting again. -You can also set `VP_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as -`prepare` or `postinstall`. +You can also set `VP_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as `prepare` or `postinstall`. -Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed to the repository. -The generated dispatcher and shims under `.vite-hooks/_` are ignored and recreated by `vp config` -or `vp hooks enable`. Neither command creates or modifies project hook scripts or staged-file -configuration. +Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed to the repository. The generated dispatcher and shims under `.vite-hooks/_` are ignored and recreated by `vp config` or `vp hooks enable`. Neither command creates or modifies project hook scripts or staged-file configuration. ### `vp staged` -`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. To run it -before each commit, add it to the project-owned pre-commit hook: +`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. To run it before each commit, add it to the project-owned pre-commit hook: ```bash vp staged @@ -119,12 +106,7 @@ export default defineConfig({ }); ``` -This is the default Vite+ approach and should replace separate `lint-staged` configuration in most -projects. When you opt into hooks during `vp create`, Vite+ scaffolds both this configuration and -the corresponding pre-commit hook. During `vp migrate`, existing hook policy is preserved, and -the default is introduced only when no existing hook policy is found. Because -`vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your -lint, format, test, build, and task-runner config. +This is the default Vite+ approach and should replace separate `lint-staged` configuration in most projects. When you opt into hooks during `vp create`, Vite+ scaffolds both this configuration and the corresponding pre-commit hook. During `vp migrate`, existing hook policy is preserved, and the default is introduced only when no existing hook policy is found. Because `vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your lint, format, test, build, and task-runner config. ## Disabling Hooks in Specific Environments @@ -157,8 +139,7 @@ Because the hook itself reads this file, it works even when the committing proce ## Removing commit hooks -To stop using the Vite+ hook dispatcher in this clone (and keep `prepare` / `vp config` from -reinstalling it): +To stop using the Vite+ hook dispatcher in this clone (and keep `prepare` / `vp config` from reinstalling it): ```bash vp hooks disable @@ -170,8 +151,7 @@ This: 1. Unsets `core.hooksPath` when it points at the Vite+ dispatcher 2. Removes the generated `/_` directory -3. Records a **local** disable preference so lifecycle scripts skip reinstall until you run - `vp hooks enable` again +3. Records a **local** disable preference so lifecycle scripts skip reinstall until you run `vp hooks enable` again To re-enable: @@ -179,8 +159,7 @@ To re-enable: vp hooks enable ``` -If you no longer want hooks for the project at all (shared with teammates), also remove `vp config` -from the `prepare` or `postinstall` script in `package.json`. +If you no longer want hooks for the project at all (shared with teammates), also remove `vp config` from the `prepare` or `postinstall` script in `package.json`. ### Manual equivalent @@ -195,6 +174,4 @@ git config --local vp.hooks.disabled true # git config --local vp.hooks.dir .vite-hooks ``` -Project-owned scripts such as `.vite-hooks/pre-commit` and the `staged` block in `vite.config.ts` -can remain for later use, or you can remove them separately if the project no longer needs them. -`vp hooks disable` does **not** delete those project-owned files. +Project-owned scripts such as `.vite-hooks/pre-commit` and the `staged` block in `vite.config.ts` can remain for later use, or you can remove them separately if the project no longer needs them. `vp hooks disable` does **not** delete those project-owned files. diff --git a/docs/guide/create.md b/docs/guide/create.md index 3595624c5f..df424dc6ac 100644 --- a/docs/guide/create.md +++ b/docs/guide/create.md @@ -57,8 +57,7 @@ Run `vp create --list` to see the built-in templates and the common shorthand te - `--hooks` enables pre-commit hook setup (dispatcher + `.vite-hooks` + `staged` config) - `--no-hooks` skips hook setup -After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`. -See the [Commit hooks guide](/guide/commit-hooks). +After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`. See the [Commit hooks guide](/guide/commit-hooks). ### Dependency build scripts diff --git a/docs/guide/docker.md b/docs/guide/docker.md index 204e2294cd..11b05dfab8 100644 --- a/docs/guide/docker.md +++ b/docs/guide/docker.md @@ -6,16 +6,11 @@ Vite+ publishes an official Docker image with the `vp` CLI preinstalled: ghcr.io/voidzero-dev/vite-plus ``` -Use it for builds, CI, and devcontainers. It is not intended as a production -runtime image. +Use it for builds, CI, and devcontainers. It is not intended as a production runtime image. -`vp` resolves the Node.js version from your project (`.node-version`, -`devEngines.runtime`, or `engines.node`) and downloads that exact version during -install/build. This means the image does not need Node-version-specific tags. +`vp` resolves the Node.js version from your project (`.node-version`, `devEngines.runtime`, or `engines.node`) and downloads that exact version during install/build. This means the image does not need Node-version-specific tags. -For production, use a multi-stage build: build the app with the Vite+ image, then -copy only the resolved Node.js binary, build output, and production dependencies -into a smaller runtime image. +For production, use a multi-stage build: build the app with the Vite+ image, then copy only the resolved Node.js binary, build output, and production dependencies into a smaller runtime image. ## Image tags @@ -28,19 +23,13 @@ Tags track the `vp` version: | `ghcr.io/voidzero-dev/vite-plus:.` | Latest minor | | `ghcr.io/voidzero-dev/vite-plus:..` | Exact version | -The examples use `:latest` to track the newest release; pin an exact tag or a -digest if you need reproducible builds. The image is published for `linux/amd64` -and `linux/arm64` and runs as the non-root `vp` user by default. That user has -passwordless `sudo`, so build/CI steps that need root (extra apt packages, -`playwright install --with-deps`) work without changing the image user. +The examples use `:latest` to track the newest release; pin an exact tag or a digest if you need reproducible builds. The image is published for `linux/amd64` and `linux/arm64` and runs as the non-root `vp` user by default. That user has passwordless `sudo`, so build/CI steps that need root (extra apt packages, `playwright install --with-deps`) work without changing the image user. Browse all published versions and digests on the [GitHub package page](https://github.com/voidzero-dev/vite-plus/pkgs/container/vite-plus). ## Production: SSR / Node.js server app -For apps that run Node.js in production (SvelteKit, Nuxt, a custom Vite SSR -server, and so on), build with the toolchain image and copy the resolved Node.js -and the built app into a slim runtime stage: +For apps that run Node.js in production (SvelteKit, Nuxt, a custom Vite SSR server, and so on), build with the toolchain image and copy the resolved Node.js and the built app into a slim runtime stage: ```dockerfile [Dockerfile] # syntax=docker/dockerfile:1 @@ -86,28 +75,19 @@ EXPOSE 3000 CMD ["node", "dist/server.js"] ``` -The deployed image contains only Node.js plus your app and production -dependencies, and matches `.node-version` exactly. It is much smaller than the -default `node:*` image; see the distroless tip below for the smallest result. +The deployed image contains only Node.js plus your app and production dependencies, and matches `.node-version` exactly. It is much smaller than the default `node:*` image; see the distroless tip below for the smallest result. ::: warning Prune production dependencies in a separate stage -Install production dependencies in their own `deps` stage as shown. Running -`vp install --prod` after a full `vp install` in the same stage does not remove -the already-installed devDependencies, so the `vite-plus` toolchain would be -copied into the runtime image. If your server bundle is fully self-contained (no -un-bundled runtime dependencies), you can skip copying `node_modules` entirely. +Install production dependencies in their own `deps` stage as shown. Running `vp install --prod` after a full `vp install` in the same stage does not remove the already-installed devDependencies, so the `vite-plus` toolchain would be copied into the runtime image. If your server bundle is fully self-contained (no un-bundled runtime dependencies), you can skip copying `node_modules` entirely. ::: ::: tip Smaller still -For a shell-less, minimal-CVE runtime, swap the runtime base for distroless -(`gcr.io/distroless/cc`) and keep an `ENTRYPOINT` in vector form. It is glibc -based, so the copied Node.js binary remains compatible. +For a shell-less, minimal-CVE runtime, swap the runtime base for distroless (`gcr.io/distroless/cc`) and keep an `ENTRYPOINT` in vector form. It is glibc based, so the copied Node.js binary remains compatible. ::: ## Production: static SPA / SSG -A static site needs no Node.js at runtime; serve the build output with any static -server: +A static site needs no Node.js at runtime; serve the build output with any static server: ```dockerfile [Dockerfile] FROM ghcr.io/voidzero-dev/vite-plus:latest AS build @@ -123,8 +103,7 @@ COPY --from=build /app/dist /usr/share/nginx/html ## Continuous integration -Use the image directly in container-based CI (GitLab CI, Buildkite, CircleCI, -Jenkins, and others): +Use the image directly in container-based CI (GitLab CI, Buildkite, CircleCI, Jenkins, and others): ```yaml [.gitlab-ci.yml] build: @@ -140,11 +119,7 @@ On GitHub Actions, prefer [`setup-vp`](./ci) instead of the image. ## Browser mode tests (Vitest / Playwright) -Running as the non-root `vp` user is what you want for browsers: Chromium keeps -its sandbox (running a browser as root disables it). Install the browser and its -system libraries in the job. `playwright install --with-deps` needs root to -`apt-get install` those libraries. The `vp` user has passwordless `sudo`, so -Playwright uses it to install them without changing the image user: +Running as the non-root `vp` user is what you want for browsers: Chromium keeps its sandbox (running a browser as root disables it). Install the browser and its system libraries in the job. `playwright install --with-deps` needs root to `apt-get install` those libraries. The `vp` user has passwordless `sudo`, so Playwright uses it to install them without changing the image user: ```yaml [.gitlab-ci.yml] test: @@ -155,15 +130,9 @@ test: - vp test ``` -`vp exec` runs the project's own Playwright (from your lockfile), so it installs -the browser revision your tests expect. Prefer it over `vpx playwright install`, -which would download whatever Playwright is latest and can fetch a different -browser revision. +`vp exec` runs the project's own Playwright (from your lockfile), so it installs the browser revision your tests expect. Prefer it over `vpx playwright install`, which would download whatever Playwright is latest and can fetch a different browser revision. -To bake the browser and its libraries into a derived image instead of installing -them on every run, install the project dependencies first so the baked browser -matches your lockfile, then install with the project's Playwright (root is -available through `sudo`): +To bake the browser and its libraries into a derived image instead of installing them on every run, install the project dependencies first so the baked browser matches your lockfile, then install with the project's Playwright (root is available through `sudo`): ```dockerfile [Dockerfile] FROM ghcr.io/voidzero-dev/vite-plus:latest @@ -173,13 +142,11 @@ RUN vp install --frozen-lockfile RUN vp exec playwright install --with-deps chromium ``` -If Chromium crashes under load in CI, give the container more shared memory with -`--ipc=host`; see the [Playwright Docker docs](https://playwright.dev/docs/docker). +If Chromium crashes under load in CI, give the container more shared memory with `--ipc=host`; see the [Playwright Docker docs](https://playwright.dev/docs/docker). ## Devcontainers -Use the image as a ready-to-go development container with the toolchain -preinstalled: +Use the image as a ready-to-go development container with the toolchain preinstalled: ```jsonc [.devcontainer/devcontainer.json] { @@ -197,23 +164,8 @@ docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp bui ## Notes -- **Node.js version**: provisioned from `.node-version`, `engines.node`, or - `devEngines.runtime` at build time, so there is no Node.js-specific image tag. The - dependency `COPY` uses a `.node-version*` glob so the file is optional: projects - that pin via `engines.node`/`devEngines.runtime` need no `.node-version`, and - those that use one have it available in every stage. -- **Non-root user**: the image runs as the non-root `vp` user, so copy sources - with `COPY --chown=vp:vp ...` as shown. Without it, `COPY` writes root-owned - files that `vp install` cannot update (permission denied). The `vp` user has - passwordless `sudo` for the occasional root step (installing extra apt packages - or `playwright install --with-deps`), so you rarely need to switch the image - user. The production runtime stage is a separate, vp-free base image, so this - convenience does not reach your deployed image. -- **Native addons**: the image includes a C/C++ build toolchain (`build-essential`, - `python3`), so native dependencies such as `better-sqlite3` compile during - `vp install`. -- **glibc**: the image is glibc based so it uses the official, signature-verified - Node.js builds. -- **Custom base image**: to add `vp` to your own base image instead, run the - installer: `curl -fsSL https://vite.plus | bash` (set `VP_VERSION` to pin a - version). +- **Node.js version**: provisioned from `.node-version`, `engines.node`, or `devEngines.runtime` at build time, so there is no Node.js-specific image tag. The dependency `COPY` uses a `.node-version*` glob so the file is optional: projects that pin via `engines.node`/`devEngines.runtime` need no `.node-version`, and those that use one have it available in every stage. +- **Non-root user**: the image runs as the non-root `vp` user, so copy sources with `COPY --chown=vp:vp ...` as shown. Without it, `COPY` writes root-owned files that `vp install` cannot update (permission denied). The `vp` user has passwordless `sudo` for the occasional root step (installing extra apt packages or `playwright install --with-deps`), so you rarely need to switch the image user. The production runtime stage is a separate, vp-free base image, so this convenience does not reach your deployed image. +- **Native addons**: the image includes a C/C++ build toolchain (`build-essential`, `python3`), so native dependencies such as `better-sqlite3` compile during `vp install`. +- **glibc**: the image is glibc based so it uses the official, signature-verified Node.js builds. +- **Custom base image**: to add `vp` to your own base image instead, run the installer: `curl -fsSL https://vite.plus | bash` (set `VP_VERSION` to pin a version). diff --git a/docs/guide/env.md b/docs/guide/env.md index 7a7429de48..271e851d68 100644 --- a/docs/guide/env.md +++ b/docs/guide/env.md @@ -1,12 +1,21 @@ # Environment -`vp env` manages the complete JavaScript environment: one Node.js runtime and one selected package manager. npm, pnpm, Yarn, and Bun are peer package-manager families. +`vp env` manages the complete JavaScript environment: one Node.js runtime and one selected package manager. npm, pnpm, Yarn, and Bun are peer package-manager families. It belongs to the [global CLI](/guide/global-cli) and is not included in the project-local `vite-plus` package. ## Overview +Think of the project environment as two independently selected components: + +- **Node.js** is the runtime used to execute JavaScript tools and scripts. Each project can declare the Node.js version it needs. +- **The package manager** installs and manages project dependencies. Each project can select npm, pnpm, Yarn, or Bun and declare its version. + +For example, a project can use Node.js 24 with pnpm 10. Changing its Node.js version does not change its package-manager selection, and switching from pnpm to Yarn does not change its Node.js version. Vite+ resolves both components when you run a command so that you can move between projects without manually switching tools. + +Vite+ connects these selections to your shell through **shims**: small launchers named `node`, `npm`, `pnpm`, `yarn`, and `bun`, along with their aliases. In managed mode, a shim resolves and launches the appropriate tool for the current project. Commands such as `vp install` use the project's selected package manager; invoking `pnpm` directly always runs pnpm, even in a project that selects another manager. + Managed mode is on by default, so Node.js and configured package-manager shims resolve through Vite+ and pick the right versions for the current project. Fresh installers record managed mode for npm, pnpm, Yarn, and Bun after the user enables environment management. -When an upgrade adds a package-manager shim that has no recorded mode, its first interactive invocation asks what to do only when the corresponding system binary is already on PATH. The current family defaults to managed mode; choosing a system tool or applying a choice to every family remains explicit. Non-interactive invocations use managed mode without recording a choice. +Use `vp env off` to disable managed mode for Node.js and package managers. See [Environment Modes](#environment-modes) below for details and how to switch to system tools. Most commands operate on both components when no selector is given. Add `node`, `pm`, `npm`, `pnpm`, `yarn`, or `bun` to narrow the command. `pm` means all four families for listing and cleanup, but the single selected package manager for project operations. @@ -19,16 +28,18 @@ vp env pin node@24 pnpm@12 # Both components vp env pin 22.0.0 pnpm@10.18.0 # Also both components ``` -Vite+ checks the current directory first, then walks up through its parents. The nearest directory -with a supported declaration wins. Within each directory, sources are checked in this order: +Use `vp env pin` to save a project's versions, `vp env default` to set fallback versions, and `vp env use` to override versions for the current shell. Run `vp env current` to see the resolved environment. + +## Node.js Selection + +To select the project's Node.js version, Vite+ checks the current directory first, then walks up through its parents. The nearest directory with a supported declaration wins. Within each directory, sources are checked in this order: 1. `.node-version` file 2. `devEngines.runtime` in `package.json` (the [devEngines standard](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines)) 3. `engines.node` in `package.json` 4. `.nvmrc` file -If no directory declares a version, Vite+ uses the global default (`vp env default`) and then the -latest LTS. +If no directory declares a version, Vite+ uses the global default (`vp env default`) and then the latest LTS. `devEngines.runtime` ranks above `engines.node` because it declares the development-environment requirement, while `engines.node` is a consumer-facing support range. `vp env doctor` warns when declared sources conflict. @@ -44,6 +55,8 @@ pnpm config set --global runtimeOnFail ignore This setting also disables pnpm's automatic management of other declared runtimes, including Bun and Deno. Consider whether any of your projects rely on that behavior before setting it globally. ::: +## Package-Manager Selection + Package-manager selection uses this priority: 1. Explicit command override @@ -76,16 +89,17 @@ VP_PNPM_VERSION=10.20.0 pnpm --version The overrides apply in managed mode. A package manager can also perform its own version switching after Vite+ launches it; for example, pnpm's `managePackageManagerVersions` setting may switch back to the version in `package.json`. -A project selection applies only to its matching shims. For example, pnpm controls `pnpm` and `pnpx`; invoking `npm` still resolves npm independently. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The resolved version is cached for one hour and an expired cache remains available when the registry cannot be reached. The directly invoked npm shim keeps its Node-bundled fallback, while an explicit `vp env ... npm` family scope uses standalone npm's latest release. +A project selection applies only to its matching shims. For example, pnpm controls `pnpm` and `pnpx`; invoking `npm` still resolves npm independently. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The directly invoked npm shim keeps its Node-bundled fallback, while an explicit `vp env ... npm` family scope uses standalone npm's latest release. + +::: details Latest-version caching +When a named shim falls back to the latest release, the resolved version is cached for one hour. An expired cache remains available when the registry cannot be reached. +::: -A fresh install uses the split platform layout by default. On Unix, Vite+ -stores managed runtimes and related files in `~/.local/share/vite-plus`. It -stores executables in the Vite+-owned `~/.local/share/vite-plus/bin` directory. -On Windows, Vite+ uses `%LOCALAPPDATA%\vite-plus\data` for data and -`%LOCALAPPDATA%\vite-plus\bin` for executables. Vite+ does not move an existing -`~/.vite-plus` install. `VP_HOME` puts all categories under one custom root. +## Environment Modes + +Managed mode is on by default, so Node.js and configured package-manager shims resolve through Vite+ and pick the right versions for the current project. Fresh installers record managed mode for npm, pnpm, Yarn, and Bun after the user enables environment management. -If you want to keep that behavior, run: +To enable managed mode, run: ```bash vp env on @@ -124,8 +138,7 @@ PowerShell needs to dot-source the generated setup script in the current shell b . "$env:APPDATA\vite-plus\env.ps1" ``` -If an older Vite+ install uses `%USERPROFILE%\.vite-plus`, source the `env.ps1` -file in that directory instead. +If an older Vite+ install uses `%USERPROFILE%\.vite-plus`, source the `env.ps1` file in that directory instead. Add that line to the end of your PowerShell `$PROFILE` to apply it automatically in new shells. It does not require elevated privileges. @@ -151,10 +164,7 @@ vp-use --unset Only `vp env use` needs this alternate command. Other `vp env` commands work normally in Command Prompt. `vp env setup` creates `vp-use.cmd` in the bin directory on Windows. -In CI, `vp env use` can run without shell initialization. It writes a temporary -session file per runtime or package manager in the resolved state directory, -such as `.session-node-version` or `.session-pnpm-version`. Later -shim calls in the same job use these files to resolve the same environment. +In CI, `vp env use` can run without shell initialization. It writes a temporary session file per runtime or package manager in the resolved state directory, such as `.session-node-version` or `.session-pnpm-version`. Later shim calls in the same job use these files to resolve the same environment. ### Manage diff --git a/docs/guide/global-cli.md b/docs/guide/global-cli.md new file mode 100644 index 0000000000..b682286e18 --- /dev/null +++ b/docs/guide/global-cli.md @@ -0,0 +1,348 @@ +# Global CLI + +The global CLI is a standalone `vp` binary for machine-level runtime and package management. It includes a Vite+ toolchain, does not require Node.js to be installed first, and can be used without adding `vite-plus` to a project. + +Choose the global CLI when you want one command available across projects for any combination of: + +- managing Node.js and package-manager versions +- selecting and downloading package managers +- installing dependencies and running package binaries +- running `package.json` scripts and cached workspace tasks +- using the Vite+ frontend toolchain without pinning it in every project + +Installing the global CLI does not require you to adopt the project-local package. You can use it only for runtime management, package management, and the task runner if that is all you need. + +## Install + +::: code-group + +```bash [macOS / Linux] +curl -fsSL https://vite.plus | bash +``` + +```powershell [Windows] +irm https://vite.plus/ps1 | iex +``` + +::: + +On Windows, you can instead download and run [`vp-setup.exe`](https://setup.viteplus.dev). + +After installation, open a new shell and run: + +```bash +vp help +``` + +When you enable environment management during installation, Vite+ records managed mode for Node.js and the npm, pnpm, Yarn, and Bun shims. Run `vp env off` to prefer system tools, or scope the change with `vp env off node` or `vp env off pm`. + +::: details Installer Environment Variables & Options + +The Vite+ installers (`vp-setup.exe`, `install.ps1`, and `install.sh`) and the installed `vp` CLI read the environment variables below. + +### Installation Variables + +These variables control the installer scripts and the standalone Windows installer (`vp-setup.exe`). + +#### `VP_VERSION` + +- **Purpose**: Version to install +- **Default**: `latest` +- **CLI equivalent**: `--version` +- **Note**: Vite+ 0.2.x and earlier do not support the split directory layout. The installer always puts these releases in the monolithic root (`VP_HOME` or `~/.vite-plus`). This rule also applies to a fresh machine. The installer checks the downloaded binary and prints a notice. +- **Example**: + + ```bash + # Unix + curl -fsSL https://vite.plus | VP_VERSION=1.2.3 bash + ``` + + ```powershell + # PowerShell + $env:VP_VERSION = "1.2.3"; irm https://vite.plus/ps1 | iex + ``` + +#### `VP_HOME` + +- **Purpose**: Optional pin for the single-root layout. Set it to an absolute path. Vite+ then puts bin, data, cache, config, and state under that directory. The installed CLI reads the same variable. See [Environment](/guide/env). +- **Default**: unset. Vite+ reuses an existing install in `~/.vite-plus` on Unix or `%USERPROFILE%\.vite-plus` on Windows. The directory must contain a `current` link. Otherwise, a fresh install uses the split platform layout. On Unix, it uses `~/.local/share/vite-plus` and its Vite+-owned `bin` subdirectory. On Windows, it uses `%LOCALAPPDATA%\vite-plus\data` and `%LOCALAPPDATA%\vite-plus\bin`. +- **Example**: + + ```bash + # Unix + curl -fsSL https://vite.plus | VP_HOME=/opt/vite-plus bash + ``` + + ```powershell + # PowerShell + $env:VP_HOME = "D:\vite-plus"; irm https://vite.plus/ps1 | iex + ``` + +#### `VP_BIN_DIR` / `VP_DATA_DIR` / `VP_CACHE_DIR` + +- **Purpose**: Internal absolute directory overrides for integrations that must pin a split install. Set all three variables together. The installer rejects an incomplete group. Vite+ ignores the group when `VP_HOME` is set or when it reuses an existing `~/.vite-plus` install. +- **Default**: unset (XDG / platform defaults) +- **Persistence**: The generated environment file does not export these variables. An integration that uses them must provide the complete group to each Vite+ process. +- **Example**: + + ```bash + export VP_DATA_DIR=$HOME/vite-plus-data + export VP_BIN_DIR=$VP_DATA_DIR/bin + export VP_CACHE_DIR=$HOME/.cache/vite-plus + curl -fsSL https://vite.plus | bash + ``` + +#### `NPM_CONFIG_REGISTRY` + +- **Purpose**: Custom npm registry URL +- **Default**: `https://registry.npmjs.org` +- **CLI equivalent**: `--registry` +- **Example**: + ```bash + curl -fsSL https://vite.plus | NPM_CONFIG_REGISTRY=https://registry.npmmirror.com bash + ``` + +#### `VP_NODE_MANAGER` + +- **Purpose**: Control Node.js version manager setup during installation. +- **Values**: `yes` or `no` +- **Default**: Auto-detected +- **CLI equivalent**: `--no-node-manager` (inverted) +- **Example**: + ```bash + # Skip Node.js manager setup in CI + curl -fsSL https://vite.plus | VP_NODE_MANAGER=no bash + ``` + +#### `VP_PM_MANAGER` + +- **Purpose**: Set the management preference for all four package-manager families: npm, pnpm, Yarn, and Bun. +- **Values**: `yes` uses Vite+ management; `no` prefers system tools, with managed tools as a fallback when a system tool is unavailable. +- **Default**: Unset. The installer's combined Node.js and package-manager choice remains the default. With the script installers, setting only `VP_NODE_MANAGER` preserves existing package-manager preferences. + +#### `VP_NPM_MANAGER` / `VP_PNPM_MANAGER` / `VP_YARN_MANAGER` / `VP_BUN_MANAGER` + +- **Purpose**: Set the management preference for an individual package-manager family. Each variable overrides `VP_PM_MANAGER` for that family. +- **Values**: `yes` or `no`, with the same meaning as `VP_PM_MANAGER`. +- **Default**: Unset (use `VP_PM_MANAGER`, then the combined installer choice, or preserve the existing preference). +- **Example**: + + ```bash + # Keep system Node.js and package managers, but let Vite+ manage pnpm. + curl -fsSL https://vite.plus | VP_NODE_MANAGER=no VP_PM_MANAGER=no VP_PNPM_MANAGER=yes bash + ``` + +These management variables are installation choices, saved in Vite+'s config. The interactive prompt still controls both Node.js and package managers; explicit package-manager variables override that combined choice. The standalone `vp-setup` installer uses its existing combined option as the default for both variables, in interactive and silent installations alike. In-place upgrades preserve the saved choices. Unrecognized values are ignored. They select management behavior, not package-manager versions, and do not prevent the installer from creating shims. Older releases installed through the legacy installer retain their original behavior. + +#### `VP_PR_VERSION` + +- **Purpose**: Install a preview build from a pull request or commit SHA +- **Values**: PR number or commit SHA +- **Default**: None +- **Details**: [Global `vp` Preview](/guide/upgrade#global-vp-preview) + +#### Development variables + +Use `VP_LOCAL_TGZ` and `VP_LOCAL_BINARY` when you develop Vite+ itself. `VP_LOCAL_TGZ` specifies a local `vite-plus.tgz` file. `VP_LOCAL_BINARY` specifies a local `vp` binary. The installers use these files for the local build. They use `VP_DUMP_DIRS=1` to get the layout mode and all five `EnvConfig` category roots from the selected binary. They do not resolve the directory variables. The installers set `VP_INSTALL_STOP`; do not set it manually. + +### Runtime Variables + +These variables configure the installed Vite+ CLI. `VP_HOME` (above) also applies at runtime. + +#### `VP_NODE_DIST_MIRROR` + +- **Purpose**: Node.js distribution mirror URL +- **Default**: `https://nodejs.org/dist` +- **Details**: [Custom Node.js Mirror](/guide/env#custom-node-js-mirror) + +#### `VP_NODE_VERSION` + +- **Purpose**: Override Node.js version +- **Default**: None (auto-detected) +- **Example**: + ```bash + # Run a command with a specific Node.js version + VP_NODE_VERSION=22 vp env exec node -v + ``` + +#### `VP_PACKAGE_MANAGER` + +- **Purpose**: Override the selected package manager and version +- **Default**: None (resolved from the project or global default) +- **Format**: `npm|pnpm|yarn|bun@` +- **Example**: + ```bash + VP_PACKAGE_MANAGER=pnpm@10.18.0 vp install + ``` + +#### `VP_NODE_SKIP_SIGNATURE_VERIFY` + +- **Purpose**: Skip PGP signature verification of Node.js downloads +- **Values**: Any non-empty value +- **Default**: None (verification enabled) +- **Details**: [Node.js Signature Verification](/guide/env#node-js-signature-verification) + +#### `VP_DOWNLOAD_TIMEOUT` + +- **Purpose**: Per-request timeout, in seconds, for large downloads such as Node.js runtimes and package-manager tarballs +- **Values**: Positive integer, at most `86400` (24 hours); invalid values are ignored with a warning +- **Default**: `600` (10 minutes) +- **Example**: + ```bash + # Allow up to 30 minutes per download on a slow connection + VP_DOWNLOAD_TIMEOUT=1800 vp env install 22 + ``` + +#### `VP_SHELL` + +- **Purpose**: Specify the current shell +- **Default**: Auto-detected +- **Example**: + ```bash + VP_SHELL=bash vp env print + ``` + +#### `VP_BYPASS` + +- **Purpose**: Bypass the Vite+ shim and use the system tool +- **Values**: `PATH`-style list of directories to bypass +- **Default**: None +- **Example**: + ```bash + VP_BYPASS=/usr/local/bin node -v + ``` + +#### Internal variables + +Vite+ sets additional `VP_*` variables during shim dispatch and shell integration (recursion guards, active-version records, wrapper flags); do not set them manually. + +### TLS/CA Configuration + +#### `SSL_CERT_FILE` / `NODE_EXTRA_CA_CERTS` + +- **Purpose**: Path to PEM bundle of extra CA certificates (`NODE_EXTRA_CA_CERTS` is the Node.js convention) +- **Default**: System trust store +- **Example**: + ```bash + export SSL_CERT_FILE=/path/to/custom-ca.pem + ``` + +#### `VP_INSECURE_TLS` + +- **Purpose**: Disable HTTPS certificate verification +- **Values**: Any non-empty value (`1`, `true`, `yes`) +- **Default**: None (verification enabled) +- **Warning**: Diagnostic escape hatch only; do not use in production +- **Example**: + ```bash + VP_INSECURE_TLS=1 vp env install 22 + ``` + +### Logging and Debugging + +#### `VP_LOG` + +- **Purpose**: Log filter string for `tracing_subscriber` +- **Installer behavior**: When `CI=true`, `install.sh` hides shell file errors. Set `VP_LOG=trace` to show these errors. +- **Default**: None +- **Example**: + ```bash + VP_LOG=debug vp dev + VP_LOG=vt=trace vp build + ``` + +#### `VP_DEBUG_SHIM` + +- **Purpose**: Enable debug output for shim dispatch +- **Values**: Any non-empty value +- **Default**: None +- **Example**: + ```bash + VP_DEBUG_SHIM=1 node -v + ``` + +### Standard Environment Variables + +Vite+ also respects these standard environment variables: + +#### `CI` + +- **Purpose**: Indicates running in CI environment +- **Effect**: Enables silent mode (`--yes`) for installers + +#### `NO_COLOR` + +- **Purpose**: Disable colored output +- **Effect**: Disables ANSI color codes + +#### `HOME` / `USERPROFILE` + +- **Purpose**: User home directory +- **Effect**: Base for the existing-install probe (`~/.vite-plus`) and for split platform defaults + +### Precedence + +1. CLI flags (highest priority) +2. Environment variables +3. Default values (lowest priority) + +For example, `VP_VERSION=1.0.0 vp-setup.exe --version 2.0.0` installs version 2.0.0. + +::: + +## Use It Without a Local Package + +The global installation is enough for runtime, package-manager, and task-runner workflows: + +```bash +vp env pin lts # Pin and install Node.js for this project +vp install # Use the package manager declared by the project +vp run build # Run a package.json script or configured task +vp dlx create-vite # Download and run a package binary +``` + +You do not need a local `vite-plus` dependency to run existing `package.json` scripts. Add the [project-local CLI](/guide/local-cli) when you want the frontend toolchain version recorded in the project's manifest and lockfile. + +## Use Both CLIs Together + +The global CLI and the project-local `vite-plus` package work together. You keep using the same `vp` command, while each project can choose its own toolchain version. + +For development commands such as `vp dev`, `vp build`, `vp test`, and `vp run`, the global CLI delegates to the project's installed version when available: + +| Current project | Toolchain used by `vp` | +| ----------------------------------- | --------------------------------- | +| Has `vite-plus` installed locally | The project's installed toolchain | +| Does not have `vite-plus` installed | The globally installed toolchain | + +In a monorepo, the local installation can be shared at the workspace root. You do not need to install `vite-plus` separately in every package. + +For example, if a project has Vite+ version A installed and your global installation is version B, `vp build` uses version A's toolchain. Upgrading the global installation does not change that project's installed toolchain. + +Package-manager commands such as `vp install` and `vp add` use the global CLI. Commands for managing your environment or global installation, such as `vp env`, `vp upgrade`, and `vp implode`, also stay with the global CLI regardless of the project's version. + +To see which toolchain is selected for your current project, run `vp toolchain`. Use `vp toolchain --global` to inspect the global installation. + +## Next Steps + +- [Environment](/guide/env) covers Node.js and package-manager selection, pinning, shims, and managed installations. +- [Package Management](/guide/install) covers pnpm, npm, Yarn, and Bun workflows. +- [Run](/guide/run) covers package scripts and cached workspace tasks. +- [Upgrading Vite+](/guide/upgrade) explains global CLI upgrades. See [Update Vite+](/guide/upgrade-project) for project-local upgrades. +- [Removing Vite+](/guide/implode) removes the global binary and its managed data. + +::: details Platform support + +Prebuilt binaries are distributed for: + +- Linux x64 and arm64 with glibc +- Windows x64 and arm64 +- macOS x64 and arm64 +- Linux x64 and arm64 with musl + +If a prebuilt binary is not available for your platform, installation fails with an error. On Alpine Linux, install `libstdc++` before using the managed [unofficial Node.js builds](https://unofficial-builds.nodejs.org/): + +```sh +apk add libstdc++ +``` + +::: diff --git a/docs/guide/ide-integration.md b/docs/guide/ide-integration.md index 47637e6d13..2e2e3549a1 100644 --- a/docs/guide/ide-integration.md +++ b/docs/guide/ide-integration.md @@ -120,8 +120,7 @@ For the best Vite+ experience with JetBrains IDEs such as IntelliJ & WebStorm, i When you create or migrate a project, Vite+ prompts you to choose whether you want the editor config written for JetBrains IDEs. ::: tip Vite+ does not merge with existing config files -Due to some complexities with merging XML files, Vite+ currently does not merge your current files if the files already exist. -You'll be given the opportunity to replace any existing files, instead of merging. +Due to some complexities with merging XML files, Vite+ currently does not merge your current files if the files already exist. You'll be given the opportunity to replace any existing files, instead of merging. ::: You can also manually set up the IDE configuration to match your Vite+ setup: diff --git a/docs/guide/implode.md b/docs/guide/implode.md index 02a019f5f6..2584ce998d 100644 --- a/docs/guide/implode.md +++ b/docs/guide/implode.md @@ -1,6 +1,6 @@ # Removing Vite+ -Use `vp implode` to remove `vp` and all related Vite+ data from your machine. +Use `vp implode` to remove the [global `vp` installation](/guide/global-cli) and all related Vite+ data from your machine. It does not remove `vite-plus` dependencies from projects. ## Overview diff --git a/docs/guide/index.md b/docs/guide/index.md index 10f8bacec9..a4b9144188 100644 --- a/docs/guide/index.md +++ b/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. + +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 ready-made setup prompt: -## 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,7 @@ 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`. After installation, open a new shell and run: @@ -71,7 +77,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 +88,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 `](/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 `](/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 ` or `vpr `. diff --git a/docs/guide/install.md b/docs/guide/install.md index e30e6bb61c..d2c066a738 100644 --- a/docs/guide/install.md +++ b/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 @` 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 ` 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 `. 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 # 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. diff --git a/docs/guide/installer-env-vars.md b/docs/guide/installer-env-vars.md deleted file mode 100644 index c6cad0c25a..0000000000 --- a/docs/guide/installer-env-vars.md +++ /dev/null @@ -1,286 +0,0 @@ -# Installer Environment Variables - -The Vite+ installers (`vp-setup.exe`, `install.ps1`, and `install.sh`) and the installed `vp` CLI read the environment variables on this page. - -## Installation Variables - -These variables control the installer scripts and the standalone Windows installer (`vp-setup.exe`). - -### `VP_VERSION` - -- **Purpose**: Version to install -- **Default**: `latest` -- **CLI equivalent**: `--version` -- **Note**: Vite+ 0.2.x and earlier do not support the split directory layout. - The installer always puts these releases in the monolithic root (`VP_HOME` or - `~/.vite-plus`). This rule also applies to a fresh machine. The installer - checks the downloaded binary and prints a notice. -- **Example**: - - ```bash - # Unix - curl -fsSL https://vite.plus | VP_VERSION=1.2.3 bash - ``` - - ```powershell - # PowerShell - $env:VP_VERSION = "1.2.3"; irm https://vite.plus/ps1 | iex - ``` - -### `VP_HOME` - -- **Purpose**: Optional pin for the single-root layout. Set it to an absolute - path. Vite+ then puts bin, data, cache, config, and state under that directory. - The installed CLI reads the same variable. See [Environment](/guide/env). -- **Default**: unset. Vite+ reuses an existing install in `~/.vite-plus` on - Unix or `%USERPROFILE%\.vite-plus` on Windows. The directory must contain a - `current` link. Otherwise, a fresh install uses the split platform layout. On - Unix, it uses `~/.local/share/vite-plus` and its Vite+-owned `bin` - subdirectory. On Windows, it uses `%LOCALAPPDATA%\vite-plus\data` and - `%LOCALAPPDATA%\vite-plus\bin`. -- **Example**: - - ```bash - # Unix - curl -fsSL https://vite.plus | VP_HOME=/opt/vite-plus bash - ``` - - ```powershell - # PowerShell - $env:VP_HOME = "D:\vite-plus"; irm https://vite.plus/ps1 | iex - ``` - -### `VP_BIN_DIR` / `VP_DATA_DIR` / `VP_CACHE_DIR` - -- **Purpose**: Internal absolute directory overrides for integrations that - must pin a split install. Set all three variables together. The installer - rejects an incomplete group. Vite+ ignores the group when `VP_HOME` is set - or when it reuses an existing `~/.vite-plus` install. -- **Default**: unset (XDG / platform defaults) -- **Persistence**: The generated environment file does not export these - variables. An integration that uses them must provide the complete group to - each Vite+ process. -- **Example**: - - ```bash - export VP_DATA_DIR=$HOME/vite-plus-data - export VP_BIN_DIR=$VP_DATA_DIR/bin - export VP_CACHE_DIR=$HOME/.cache/vite-plus - curl -fsSL https://vite.plus | bash - ``` - -### `NPM_CONFIG_REGISTRY` - -- **Purpose**: Custom npm registry URL -- **Default**: `https://registry.npmjs.org` -- **CLI equivalent**: `--registry` -- **Example**: - ```bash - curl -fsSL https://vite.plus | NPM_CONFIG_REGISTRY=https://registry.npmmirror.com bash - ``` - -### `VP_NODE_MANAGER` - -- **Purpose**: Control Node.js version manager setup during installation. -- **Values**: `yes` or `no` -- **Default**: Auto-detected -- **CLI equivalent**: `--no-node-manager` (inverted) -- **Example**: - ```bash - # Skip Node.js manager setup in CI - curl -fsSL https://vite.plus | VP_NODE_MANAGER=no bash - ``` - -### `VP_PM_MANAGER` - -- **Purpose**: Set the management preference for all four package-manager - families: npm, pnpm, Yarn, and Bun. -- **Values**: `yes` uses Vite+ management; `no` prefers system tools, with - managed tools as a fallback when a system tool is unavailable. -- **Default**: Unset. The installer's combined Node.js and package-manager - choice remains the default. With the script installers, setting only - `VP_NODE_MANAGER` preserves existing package-manager preferences. - -### `VP_NPM_MANAGER` / `VP_PNPM_MANAGER` / `VP_YARN_MANAGER` / `VP_BUN_MANAGER` - -- **Purpose**: Set the management preference for an individual package-manager - family. Each variable overrides `VP_PM_MANAGER` for that family. -- **Values**: `yes` or `no`, with the same meaning as `VP_PM_MANAGER`. -- **Default**: Unset (use `VP_PM_MANAGER`, then the combined installer choice, - or preserve the existing preference). -- **Example**: - - ```bash - # Keep system Node.js and package managers, but let Vite+ manage pnpm. - curl -fsSL https://vite.plus | VP_NODE_MANAGER=no VP_PM_MANAGER=no VP_PNPM_MANAGER=yes bash - ``` - -These management variables are installation choices, saved in Vite+'s config. -The interactive prompt still controls both Node.js and package managers; -explicit package-manager variables override that combined choice. The standalone -`vp-setup` installer uses its existing combined option as the default for both -variables, in interactive and silent installations alike. -In-place upgrades preserve the saved choices. Unrecognized values are ignored. -They select management behavior, not package-manager versions, and do not -prevent the installer from creating shims. Older releases installed through -the legacy installer retain their original behavior. - -### `VP_PR_VERSION` - -- **Purpose**: Install a preview build from a pull request or commit SHA -- **Values**: PR number or commit SHA -- **Default**: None -- **Details**: [Global `vp` Preview](/guide/upgrade#global-vp-preview) - -### Development variables - -Use `VP_LOCAL_TGZ` and `VP_LOCAL_BINARY` when you develop Vite+ itself. -`VP_LOCAL_TGZ` specifies a local `vite-plus.tgz` file. `VP_LOCAL_BINARY` -specifies a local `vp` binary. The installers use these files for the local -build. They use `VP_DUMP_DIRS=1` to get the layout mode and all five `EnvConfig` -category roots from the selected binary. They do not resolve the directory -variables. The installers set `VP_INSTALL_STOP`; do not set it manually. - -## Runtime Variables - -These variables configure the installed Vite+ CLI. `VP_HOME` (above) also applies at runtime. - -### `VP_NODE_DIST_MIRROR` - -- **Purpose**: Node.js distribution mirror URL -- **Default**: `https://nodejs.org/dist` -- **Details**: [Custom Node.js Mirror](/guide/env#custom-node-js-mirror) - -### `VP_NODE_VERSION` - -- **Purpose**: Override Node.js version -- **Default**: None (auto-detected) -- **Example**: - ```bash - # Run a command with a specific Node.js version - VP_NODE_VERSION=22 vp env exec node -v - ``` - -### `VP_PACKAGE_MANAGER` - -- **Purpose**: Override the selected package manager and version -- **Default**: None (resolved from the project or global default) -- **Format**: `npm|pnpm|yarn|bun@` -- **Example**: - ```bash - VP_PACKAGE_MANAGER=pnpm@10.18.0 vp install - ``` - -### `VP_NODE_SKIP_SIGNATURE_VERIFY` - -- **Purpose**: Skip PGP signature verification of Node.js downloads -- **Values**: Any non-empty value -- **Default**: None (verification enabled) -- **Details**: [Node.js Signature Verification](/guide/env#node-js-signature-verification) - -### `VP_DOWNLOAD_TIMEOUT` - -- **Purpose**: Per-request timeout, in seconds, for large downloads such as Node.js runtimes and package-manager tarballs -- **Values**: Positive integer, at most `86400` (24 hours); invalid values are ignored with a warning -- **Default**: `600` (10 minutes) -- **Example**: - ```bash - # Allow up to 30 minutes per download on a slow connection - VP_DOWNLOAD_TIMEOUT=1800 vp env install 22 - ``` - -### `VP_SHELL` - -- **Purpose**: Specify the current shell -- **Default**: Auto-detected -- **Example**: - ```bash - VP_SHELL=bash vp env print - ``` - -### `VP_BYPASS` - -- **Purpose**: Bypass the Vite+ shim and use the system tool -- **Values**: `PATH`-style list of directories to bypass -- **Default**: None -- **Example**: - ```bash - VP_BYPASS=/usr/local/bin node -v - ``` - -### Internal variables - -Vite+ sets additional `VP_*` variables during shim dispatch and shell integration (recursion guards, active-version records, wrapper flags); do not set them manually. - -## TLS/CA Configuration - -### `SSL_CERT_FILE` / `NODE_EXTRA_CA_CERTS` - -- **Purpose**: Path to PEM bundle of extra CA certificates (`NODE_EXTRA_CA_CERTS` is the Node.js convention) -- **Default**: System trust store -- **Example**: - ```bash - export SSL_CERT_FILE=/path/to/custom-ca.pem - ``` - -### `VP_INSECURE_TLS` - -- **Purpose**: Disable HTTPS certificate verification -- **Values**: Any non-empty value (`1`, `true`, `yes`) -- **Default**: None (verification enabled) -- **Warning**: Diagnostic escape hatch only; do not use in production -- **Example**: - ```bash - VP_INSECURE_TLS=1 vp env install 22 - ``` - -## Logging and Debugging - -### `VP_LOG` - -- **Purpose**: Log filter string for `tracing_subscriber` -- **Installer behavior**: When `CI=true`, `install.sh` hides shell file errors. - Set `VP_LOG=trace` to show these errors. -- **Default**: None -- **Example**: - ```bash - VP_LOG=debug vp dev - VP_LOG=vt=trace vp build - ``` - -### `VP_DEBUG_SHIM` - -- **Purpose**: Enable debug output for shim dispatch -- **Values**: Any non-empty value -- **Default**: None -- **Example**: - ```bash - VP_DEBUG_SHIM=1 node -v - ``` - -## Standard Environment Variables - -Vite+ also respects these standard environment variables: - -### `CI` - -- **Purpose**: Indicates running in CI environment -- **Effect**: Enables silent mode (`--yes`) for installers - -### `NO_COLOR` - -- **Purpose**: Disable colored output -- **Effect**: Disables ANSI color codes - -### `HOME` / `USERPROFILE` - -- **Purpose**: User home directory -- **Effect**: Base for the existing-install probe (`~/.vite-plus`) and for split platform defaults - -## Precedence - -1. CLI flags (highest priority) -2. Environment variables -3. Default values (lowest priority) - -For example, `VP_VERSION=1.0.0 vp-setup.exe --version 2.0.0` installs version 2.0.0. diff --git a/docs/guide/lint.md b/docs/guide/lint.md index 467d911268..a73603f09e 100644 --- a/docs/guide/lint.md +++ b/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. diff --git a/docs/guide/local-cli.md b/docs/guide/local-cli.md new file mode 100644 index 0000000000..6a7042523b --- /dev/null +++ b/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. diff --git a/docs/guide/migrate-rules.md b/docs/guide/migrate-rules.md index a28ddea160..9cbaf93988 100644 --- a/docs/guide/migrate-rules.md +++ b/docs/guide/migrate-rules.md @@ -1,52 +1,31 @@ # 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. +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. +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. +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. +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. +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. +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`. +- `--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. +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. ## Pack Configuration -`vp migrate` updates static `pack` objects in `vite.config.*` and exported -objects in `tsdown.config.*` for [tsdown 0.23](https://github.com/rolldown/tsdown/releases/tag/v0.23.0). -This also runs on existing Vite+ projects without `--full`, including workspace -packages. Arrays and direct objects returned by `defineConfig` callbacks are -supported. JSON tsdown configs receive the same updates after they merge into -`vite.config.ts`. +`vp migrate` updates static `pack` objects in `vite.config.*` and exported objects in `tsdown.config.*` for [tsdown 0.23](https://github.com/rolldown/tsdown/releases/tag/v0.23.0). This also runs on existing Vite+ projects without `--full`, including workspace packages. Arrays and direct objects returned by `defineConfig` callbacks are supported. JSON tsdown configs receive the same updates after they merge into `vite.config.ts`. | Previous option | Updated option | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | @@ -63,27 +42,13 @@ supported. JSON tsdown configs receive the same updates after they merge into | `dts.cjsReexport` | Removed; tsdown generates CJS declarations separately | | `--public-dir` in `tsdown` or `vp pack` scripts | `--copy` | -Migration preserves the previous defaults by setting `deps.resolveDepSubpath` -to `true` when absent. Enabled ATTW checks receive `profile: 'strict'` when -no profile is set. Explicit values, including `false`, remain unchanged. +Migration preserves the previous defaults by setting `deps.resolveDepSubpath` to `true` when absent. Enabled ATTW checks receive `profile: 'strict'` when no profile is set. Explicit values, including `false`, remain unchanged. -`noExternal` moves to `deps.alwaysBundle`, preserving matcher expressions, -references, and callback methods. Existing `deps.alwaysBundle` values remain -unchanged. +`noExternal` moves to `deps.alwaysBundle`, preserving matcher expressions, references, and callback methods. Existing `deps.alwaysBundle` values remain unchanged. -When `external` accompanies either `skipNodeModulesBundle` form, static matchers -and references to local constants move to `inputOptions.external` before -`deps.neverBundle` is set. Constant declarations and references stay intact. -This preserves the original matching rules, including external file paths. Unsupported matchers, -conflicting `inputOptions`, and declaration-specific dependency rules leave the -pack object unchanged and produce a manual-migration warning. +When `external` accompanies either `skipNodeModulesBundle` form, static matchers and references to local constants move to `inputOptions.external` before `deps.neverBundle` is set. Constant declarations and references stay intact. This preserves the original matching rules, including external file paths. Unsupported matchers, conflicting `inputOptions`, and declaration-specific dependency rules leave the pack object unchanged and produce a manual-migration warning. -The transform does not evaluate configuration code. Objects with spreads, -computed keys, or duplicate keys, and conflicting old and new options require -manual review. Dynamic boolean selectors remain unchanged. Unrelated Vite and -plugin options remain unchanged. Run `vp pack` after migration to check the -result. Node.js requirements, TypeScript module resolution, and programmatic -`build()` return values require separate review. +The transform does not evaluate configuration code. Objects with spreads, computed keys, or duplicate keys, and conflicting old and new options require manual review. Dynamic boolean selectors remain unchanged. Unrelated Vite and plugin options remain unchanged. Run `vp pack` after migration to check the result. Node.js requirements, TypeScript module resolution, and programmatic `build()` return values require separate review. ## Dependency Rules @@ -99,216 +64,115 @@ What happens to each toolchain dependency, at a glance: ### 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-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. +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. +- A direct `vite` declaration is never removed merely because a root override exists. - Plain or stale aliases are normalized; named catalog references are kept. -- Under pnpm the managed override keys use an explicit `@*` range (`vite@*`, - `vitest@*`). pnpm applies an override by replacing the declared spec on every - manifest, importer manifests included. A bare key matches any spec, including - `catalog:`, and `vp up` then rewrites that reference to a concrete version. - The `@*` range keeps the override on the semver ranges that transitive and - peer declarations use. It leaves `catalog:` references to the catalog, which - already resolves them to Vite+ core. Migration re-keys a project that still - holds the bare key, and keeps its named-catalog choice. -- 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`. +- Under pnpm the managed override keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`, and `vp up` then rewrites that reference to a concrete version. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use. It leaves `catalog:` references to the catalog, which already resolves them to Vite+ core. Migration re-keys a project that still holds the bare key, and keeps its named-catalog choice. +- 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: +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; +- 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. +- 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`. +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. +- 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. +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`: +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:` 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. +- when the package manager supports catalogs, they are referenced through the toolchain catalog: an existing `catalog:` / `catalog:` 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-`, `vitest/browser/providers/`, or -`vitest/plugins/browser-`: 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. +- `@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-`, `vitest/browser/providers/`, or `vitest/plugins/browser-`: 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. +`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. +- 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. ### Oxlint JS Plugin Imports -Vite+ bundles Oxlint, so the migration removes a standalone `oxlint` -dependency. Your own Oxlint JS plugins import the authoring API by name. That -import stops resolving when the dependency goes away. `vp lint` then fails to -load the plugin. +Vite+ bundles Oxlint, so the migration removes a standalone `oxlint` dependency. Your own Oxlint JS plugins import the authoring API by name. That import stops resolving when the dependency goes away. `vp lint` then fails to load the plugin. The migration repoints those imports at Vite+: - It rewrites `@oxlint/plugins` to `vite-plus/lint/plugins`. - It rewrites `oxlint/plugins-dev` to `vite-plus/lint/plugins-dev`. -- It rewrites `oxlint` to `vite-plus/lint/plugins` when the import names a - binding from the authoring API, such as `defineRule`, `definePlugin`, or - `Context`. Older Oxlint releases exposed that API from the main entry. It now - lives in `@oxlint/plugins`. +- It rewrites `oxlint` to `vite-plus/lint/plugins` when the import names a binding from the authoring API, such as `defineRule`, `definePlugin`, or `Context`. Older Oxlint releases exposed that API from the main entry. It now lives in `@oxlint/plugins`. -An import through Vite+ always matches the version of Oxlint that Vite+ -bundles. You pin no second package. The import also resolves from any package -that already depends on `vite-plus`. +An import through Vite+ always matches the version of Oxlint that Vite+ bundles. You pin no second package. The import also resolves from any package that already depends on `vite-plus`. The migration leaves three forms alone: -- `oxlint` imports that name only the config surface, such as `defineConfig`, - `OxlintConfig`, or `OxlintOverride`. These still resolve against the - standalone package. -- Default and namespace `oxlint` imports. They name no binding, so the - migration cannot tell the two surfaces apart. +- `oxlint` imports that name only the config surface, such as `defineConfig`, `OxlintConfig`, or `OxlintOverride`. These still resolve against the standalone package. +- Default and namespace `oxlint` imports. They name no binding, so the migration cannot tell the two surfaces apart. - Bare side-effect `oxlint` imports, for the same reason. -The migration also skips a package that declares `oxlint` or `@oxlint/plugins` -in `dependencies` or `peerDependencies`, or `@oxlint/plugins` in -`optionalDependencies`. These dependencies can supply a published Oxlint plugin. -Its consumers may not run Vite+. +The migration also skips a package that declares `oxlint` or `@oxlint/plugins` in `dependencies` or `peerDependencies`, or `@oxlint/plugins` in `optionalDependencies`. These dependencies can supply a published Oxlint plugin. Its consumers may not run Vite+. -The cleanup retains a development dependency on `@oxlint/plugins` when source, -package import aliases, or built plugins still reference it. This includes -ignored output in directories such as `dist`, `build`, and `out`. +The cleanup retains a development dependency on `@oxlint/plugins` when source, package import aliases, or built plugins still reference it. This includes ignored output in directories such as `dist`, `build`, and `out`. ### 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. +- `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: +Migration rewrites commands provided by the Vite+ toolchain in `package.json` scripts while preserving their arguments: | Before | After | | ------------- | ------------------------------------------- | @@ -322,10 +186,7 @@ scripts while preserving their arguments: | `prettier` | `vp fmt`, when its optional migration runs | | `tsup` | `vp pack`, 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 `--`: +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 | | ------------------------------------------------------- | -------------------------------------------------------- | @@ -338,112 +199,54 @@ Unrelated `bunx` commands and other package-executor forms remain unchanged. ## Continuous Integration Rules -Migration replaces exact `voidzero-dev/setup-vp@v1` references in GitHub -Actions workflows and composite actions under `.github` with the latest exact -`setup-vp` release known to that Vite+ version. The frozen `v1` tag does not -receive new releases. Existing exact versions and commit SHAs are left -unchanged. +Migration replaces exact `voidzero-dev/setup-vp@v1` references in GitHub Actions workflows and composite actions under `.github` with the latest exact `setup-vp` release known to that Vite+ version. The frozen `v1` tag does not receive new releases. Existing exact versions and commit SHAs are left 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. +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 - under `.github` (`.github/**/action.{yml,yaml}`) is repointed to - `.node-version` so CI does not fail with "node version file ... does not - exist". +- `.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 under `.github` (`.github/**/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. +**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)). +- 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. +- 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. +- 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. +- 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. +- 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. +- 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. diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md index 92f255e973..7c7b3f5314 100644 --- a/docs/guide/migrate.md +++ b/docs/guide/migrate.md @@ -22,9 +22,7 @@ The positional `PATH` argument is optional. - If omitted, `vp migrate` migrates the current directory - If provided, it migrates that target directory instead -- For a monorepo, the target must be the workspace root. Vite+ cannot - migrate one workspace member, because migration updates the package-manager - configuration, the catalogs, and the lockfiles that all members share. +- For a monorepo, the target must be the workspace root. Vite+ cannot migrate one workspace member, because migration updates the package-manager configuration, the catalogs, and the lockfiles that all members share. ```bash vp migrate @@ -53,8 +51,7 @@ The `migrate` command is designed to move existing projects onto Vite+ quickly. - 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. +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`. @@ -72,40 +69,6 @@ After running the migration: - Run `vp test` - Run `vp build` (or `vp pack` if you are building a library) -## Manual Installation & Migration - -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): - -```json -"overrides": { - "vite": "npm:@voidzero-dev/vite-plus-core@latest", - "vitest": "4.1.11" -} -``` - -If you are using `pnpm`, add this to your `pnpm-workspace.yaml`: - -```yaml -overrides: - vite: npm:@voidzero-dev/vite-plus-core@latest - vitest: 4.1.11 -``` - -Or, if you are using Yarn: - -```json -"resolutions": { - "vite": "npm:@voidzero-dev/vite-plus-core@latest", - "vitest": "4.1.11" -} -``` - ## Migration Prompt If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt: @@ -205,19 +168,13 @@ export default defineConfig({ }); ``` -When no existing hook policy owns the workflow, `vp migrate` can move supported lint-staged rules -and remove the old configuration and dependency. If an existing hook tool is preserved, keep -lint-staged in place until you convert that hook policy manually. See the -[Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details. +When no existing hook policy owns the workflow, `vp migrate` can move supported lint-staged rules and remove the old configuration and dependency. If an existing hook tool is preserved, keep lint-staged in place until you convert that hook policy manually. See the [Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details. ### Git hook tools -The `vp migrate` command does not automatically convert Husky setups. When Husky is detected, -Vite+ leaves its hooks, lifecycle scripts, configuration, and dependencies unchanged and shows a -warning. You can migrate the project manually using the [Commit hooks guide](/guide/commit-hooks). +The `vp migrate` command does not automatically convert Husky setups. When Husky is detected, Vite+ leaves its hooks, lifecycle scripts, configuration, and dependencies unchanged and shows a warning. You can migrate the project manually using the [Commit hooks guide](/guide/commit-hooks). -Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced -only when no existing hook policy is found. +Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced only when no existing hook policy is found. 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. diff --git a/docs/guide/run.md b/docs/guide/run.md index 5752752078..b1570eb0ca 100644 --- a/docs/guide/run.md +++ b/docs/guide/run.md @@ -1,6 +1,6 @@ # Run -`vp run` runs `package.json` scripts and tasks defined in `vite.config.ts`. It works like `pnpm run`, with caching, dependency ordering, and workspace-aware execution built in. +`vp run` runs `package.json` scripts and tasks defined in `vite.config.ts`. It works like `pnpm run`, with caching, dependency ordering, and workspace-aware execution built in. The task runner is available from both the [global CLI](/guide/global-cli) and the [project-local CLI](/guide/local-cli). ::: tip `vpr` is available as a standalone shorthand for `vp run`. All examples below work with both `vp run` and `vpr`. diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index 6e13007ee9..1de460c601 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -15,18 +15,14 @@ Vite+ expects modern upstream tool versions. If you are migrating an existing project and it still depends on older Vite or Vitest versions, upgrade those first before adopting Vite+. -Run `vp toolchain` to show the versions from the local Vite+ package. -Run `vp toolchain --global` to show the versions from the global Vite+ release. +Run `vp toolchain` to show the versions from the local Vite+ package. Run `vp toolchain --global` to show the versions from the global Vite+ release. ## `vp check` does not run type-aware lint rules or type checks - Confirm that `lint.options.typeAware` and `lint.options.typeCheck` are enabled in `vite.config.ts` - Check whether your `tsconfig.json` still uses `compilerOptions.baseUrl` -The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`. -`vp migrate` and `vp lint --init` try to run the `vp dlx @andrewbranch/ts5to6 --fixBaseUrl .` -fix before enabling type-aware linting. If that fix fails or is declined, Vite+ -skips `typeAware` and `typeCheck`. +The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`. `vp migrate` and `vp lint --init` try to run the `vp dlx @andrewbranch/ts5to6 --fixBaseUrl .` fix before enabling type-aware linting. If that fix fails or is declined, Vite+ skips `typeAware` and `typeCheck`. ## Nested lint or format config is not applied @@ -76,8 +72,7 @@ If `vp staged` fails or your pre-commit hook does not run: - if status shows `Preference: disabled (local)`, re-enable with `vp hooks enable` - check whether hooks were skipped intentionally through `VP_GIT_HOOKS=0` -To stop hooks in this clone without deleting project policy files, run `vp hooks disable`. -See the [Commit hooks guide](/guide/commit-hooks) for the full workflow. +To stop hooks in this clone without deleting project policy files, run `vp hooks disable`. See the [Commit hooks guide](/guide/commit-hooks) for the full workflow. A minimal staged config looks like this: diff --git a/docs/guide/upgrade-project.md b/docs/guide/upgrade-project.md new file mode 100644 index 0000000000..208586cd12 --- /dev/null +++ b/docs/guide/upgrade-project.md @@ -0,0 +1,61 @@ +# Update Vite+ + +Updating `vite-plus` and its related project dependencies. To upgrade the global `vp` binary, see [Upgrading Vite+](/guide/upgrade). + +## Update with Migrate + +The recommended way to update a project is to use `vp migrate`, which keeps the toolchain dependencies aligned. + +After updating the project's `vite-plus` dependency, run the local CLI to align the toolchain versions: + +```bash +./node_modules/.bin/vp migrate +``` + +If your global CLI is newer than the project's version, running `vp migrate` upgrades the project to that global version instead: + +```bash +vp migrate +``` + +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 bundled with the CLI running the migration, 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. + +## Manually Updating + +Update `vite-plus` and the `vite` alias to `@voidzero-dev/vite-plus-core` together, keeping the core version aligned with `vite-plus`. Update these entries wherever they are declared in your workspace, including overrides or catalogs, then install dependencies to refresh the lockfile. Also [update the Vitest pin](#updating-the-vitest-pin) to match the bundled version. + +Without the global CLI, run the `vp` commands on this page through your package manager, for example `pnpm exec vp toolchain vitest`. + +### 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`. If your `package.json` already has a `pnpm` field, the entry 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 toolchain vitest +``` + +Then set the `vitest` override to that exact version and reinstall dependencies. + +::: details Why pnpm overrides use `@*` +Under pnpm the managed keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use, and leaves `catalog:` references intact. `vp up` therefore no longer rewrites them to a concrete version. +::: + +## Preview Builds + +After [installing a preview build of the global CLI](/guide/upgrade#global-vp-preview), run migrate in the project to move its local `vite-plus` onto the same build: + +```bash +vp migrate +``` + +Migrate writes the bridge registry to `.npmrc`. For Yarn Berry, it writes the registry to `.yarnrc.yml`. It pins `vite-plus` and the `vite` alias to the matching `0.0.0-commit.` version. The `vite` alias points to `@voidzero-dev/vite-plus-core`. Commit the registry line if the project CI must test the preview. + +After the install, run `vp toolchain` to show the selected versions. After testing, set `vite-plus` to `latest`. Remove the bridge `registry` line from `.npmrc` or `.yarnrc.yml`. Then run `vp install`. diff --git a/docs/guide/upgrade.md b/docs/guide/upgrade.md index 7035e84a42..cc9ad4a641 100644 --- a/docs/guide/upgrade.md +++ b/docs/guide/upgrade.md @@ -1,13 +1,13 @@ # Upgrading Vite+ -Use `vp upgrade` to update the global `vp` binary, and use Vite+'s package management commands to update the local `vite-plus` package in a project. +Use `vp upgrade` to update the global `vp` binary. To update the local `vite-plus` package in a project, see [Update Vite+](/guide/upgrade-project). ## Overview There are two parts to upgrading Vite+: - The global `vp` command installed on your machine -- The local `vite-plus` package used by an individual project +- The [local `vite-plus` package](/guide/upgrade-project) used by an individual project You can upgrade both of them independently. @@ -22,17 +22,13 @@ vp toolchain vite rolldown oxc vp toolchain --json ``` -The command uses the local `vite-plus` package when the project has one. Use -`--global` to show the release for the global `vp` command: +The command uses the local `vite-plus` package when the project has one. Use `--global` to show the release for the global `vp` command: ```bash vp toolchain --global ``` -`vp why ` shows the dependency graph from the package manager. It -cannot show code bundled into `@voidzero-dev/vite-plus-core`. It also cannot -show engines compiled into Vite+. Use `vp toolchain` to show those versions and -relationships. +`vp why ` shows the dependency graph from the package manager. It cannot show code bundled into `@voidzero-dev/vite-plus-core`. It also cannot show engines compiled into Vite+. Use `vp toolchain` to show those versions and relationships. ## Global `vp` @@ -45,27 +41,14 @@ vp upgrade --registry # use a custom npm registry ### Move an Existing Install to the Split Directory Layout -Vite+ 0.3.0 is the first release that supports the split directory layout. -Vite+ 0.2.x and earlier use the single-root layout for fresh installs and -upgrades. +Vite+ 0.3.0 is the first release that supports the split directory layout. Vite+ 0.2.x and earlier use the single-root layout for fresh installs and upgrades. -`vp upgrade` keeps an existing default install in `~/.vite-plus` on Unix or -`%USERPROFILE%\.vite-plus` on Windows. The command upgrades the CLI in that -directory. It does not move the install to the split platform directories. You -can continue to use the existing layout. +`vp upgrade` keeps an existing default install in `~/.vite-plus` on Unix or `%USERPROFILE%\.vite-plus` on Windows. The command upgrades the CLI in that directory. It does not move the install to the split platform directories. You can continue to use the existing layout. -To use the split layout now, remove the existing install. Then install Vite+ -again. Run `vp implode` in a shell that uses the current install. The command -removes the generated environment file and shell profile entries. It does not -unset directory variables in the current shell. Unset all Vite+ directory -variables before you run the installer. This can include values from an earlier -preview environment file. Alternatively, start a new shell after `vp implode`. -Then run the installer in the new shell. +To use the split layout now, remove the existing install. Then install Vite+ again. Run `vp implode` in a shell that uses the current install. The command removes the generated environment file and shell profile entries. It does not unset directory variables in the current shell. Unset all Vite+ directory variables before you run the installer. This can include values from an earlier preview environment file. Alternatively, start a new shell after `vp implode`. Then run the installer in the new shell. ::: warning -`vp implode` removes all Vite+-managed Node.js runtimes, global packages, -configuration, and caches. Keep the existing layout if you do not want to -recreate that data. +`vp implode` removes all Vite+-managed Node.js runtimes, global packages, configuration, and caches. Keep the existing layout if you do not want to recreate that data. ::: ```bash @@ -82,11 +65,7 @@ Remove-Item Env:\VP_HOME, Env:\VP_DATA_DIR, Env:\VP_BIN_DIR, Env:\VP_CACHE_DIR - irm https://vite.plus/ps1 | iex ``` -Also remove persistent definitions of `VP_HOME`, `VP_DATA_DIR`, `VP_BIN_DIR`, -and `VP_CACHE_DIR` from your shell profile or system environment. A fresh -install uses `VP_HOME` or a complete `VP_*_DIR` group that remains set. -`VP_HOME` selects the single-root layout. If you install Vite+ 0.2.x or earlier, -the installer also uses this layout. The installer prints a notice. +Also remove persistent definitions of `VP_HOME`, `VP_DATA_DIR`, `VP_BIN_DIR`, and `VP_CACHE_DIR` from your shell profile or system environment. A fresh install uses `VP_HOME` or a complete `VP_*_DIR` group that remains set. `VP_HOME` selects the single-root layout. If you install Vite+ 0.2.x or earlier, the installer also uses this layout. The installer prints a notice. ### Rollback @@ -98,36 +77,6 @@ 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` - -The recommended way to upgrade an existing Vite+ project is `vp migrate`: - -```bash -vp migrate -``` - -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 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`. If your `package.json` already has a `pnpm` field, the entry lives under `pnpm.overrides` in `package.json` instead. pnpm ignores `pnpm-workspace.yaml` overrides when `package.json` defines `pnpm.overrides`. - -Under pnpm the managed keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use, and leaves `catalog:` references intact. `vp up` therefore no longer rewrites them to a concrete version. - -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 toolchain vitest -``` - -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. @@ -160,12 +109,4 @@ The installer uses the registry bridge to resolve the ref to a `0.0.0-commit.` version. The `vite` alias points to `@voidzero-dev/vite-plus-core`. Commit the registry line if the project CI must test the preview. - -After the install, run `vp toolchain` to show the selected versions. After testing, set `vite-plus` to `latest`. Remove the bridge `registry` line from `.npmrc` or `.yarnrc.yml`. Then run `vp install`. +To use the same preview in a project, follow [Update Vite+](/guide/upgrade-project#preview-builds). diff --git a/docs/public/_redirects b/docs/public/_redirects index 9f0ee59b59..d14f2723eb 100644 --- a/docs/public/_redirects +++ b/docs/public/_redirects @@ -1 +1,3 @@ /vp-setup https://setup.viteplus.dev 302 +/guide/installer-env-vars /guide/global-cli 301 +/guide/installer-env-vars.html /guide/global-cli 301