From 571929706677057eca58541c87527c5ed78285a0 Mon Sep 17 00:00:00 2001 From: yukinoshi <9241225+yukionno@user.noreply.gitee.com> Date: Thu, 9 Jul 2026 22:36:30 +0800 Subject: [PATCH 1/3] docs: add installer environment variables documentation - Create docs/guide/installer-env-vars.md documenting env vars used by installers (vp-setup.exe, install.ps1, install.sh) - Add links from Getting Started, Environment, Install, Docker, and Upgrade - Cover install vars (VP_VERSION, VP_HOME, NPM_CONFIG_REGISTRY, VP_NODE_MANAGER, VP_PR_VERSION, etc.) - Cover runtime vars (VP_HOME, VP_NODE_DIST_MIRROR, VP_NODE_VERSION, VP_DEBUG_SHIM, etc.) - Cover TLS/CA config (SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, VP_INSECURE_TLS) - Cover logging/debug vars (VITE_LOG, VITE_UPDATE_TASK_TYPES, etc.) - Document standard vars (CI, NO_COLOR, HOME) and precedence rules Closes #1957 --- docs/guide/docker.md | 2 +- docs/guide/env.md | 4 + docs/guide/index.md | 4 + docs/guide/install.md | 4 + docs/guide/installer-env-vars.md | 303 +++++++++++++++++++++++++++++++ docs/guide/upgrade.md | 4 + 6 files changed, 320 insertions(+), 1 deletion(-) create mode 100644 docs/guide/installer-env-vars.md diff --git a/docs/guide/docker.md b/docs/guide/docker.md index 204e2294cd..d1b3b9abe4 100644 --- a/docs/guide/docker.md +++ b/docs/guide/docker.md @@ -216,4 +216,4 @@ docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp bui 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). + version). See the [Installer Environment Variables](/guide/installer-env-vars) page for all available options. diff --git a/docs/guide/env.md b/docs/guide/env.md index 2abd62fb3d..302270af29 100644 --- a/docs/guide/env.md +++ b/docs/guide/env.md @@ -2,6 +2,10 @@ `vp env` manages Node.js versions globally and per project. +::: info +For environment variables recognized by the installer scripts (`install.ps1`, `install.sh`) and `vp-setup.exe`, see the [Installer Environment Variables](/guide/installer-env-vars) page. +::: + ## Overview Managed mode is on by default, so `node`, `npm`, and related shims resolve through Vite+ and pick the right Node.js version for the current project. diff --git a/docs/guide/index.md b/docs/guide/index.md index 884af08036..cf1f047768 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -28,6 +28,10 @@ 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"**. ::: +::: info Installer Environment Variables +The installer scripts and `vp-setup.exe` support environment variables for customization. See the [Installer Environment Variables](/guide/installer-env-vars) page for details. +::: + After installation, open a new shell and run: ```bash diff --git a/docs/guide/install.md b/docs/guide/install.md index fc0b6f4b54..52d46b59fc 100644 --- a/docs/guide/install.md +++ b/docs/guide/install.md @@ -2,6 +2,10 @@ `vp install` installs dependencies using the current workspace's package manager. +::: info +For environment variables recognized by the installer scripts (`install.ps1`, `install.sh`) and `vp-setup.exe`, see the [Installer Environment Variables](/guide/installer-env-vars) page. +::: + ## Overview Use Vite+ to manage dependencies across pnpm, npm, Yarn, and Bun. Instead of switching between `pnpm install`, `npm install`, `yarn install`, and `bun install`, you can keep using `vp install`, `vp add`, `vp remove`, and the rest of the Vite+ package-management commands. diff --git a/docs/guide/installer-env-vars.md b/docs/guide/installer-env-vars.md new file mode 100644 index 0000000000..cfe08559da --- /dev/null +++ b/docs/guide/installer-env-vars.md @@ -0,0 +1,303 @@ +# Installer Environment Variables + +This page documents all environment variables recognized by the Vite+ installers (`vp-setup.exe`, `install.ps1`, and `install.sh`). + +::: tip +The set of supported variables may change between releases. Always check the [release notes](https://github.com/voidzero-dev/vite-plus/releases) for the version you are using. +::: + +## Installation Variables + +These variables control the behavior of the Vite+ installer scripts and the standalone Windows installer (`vp-setup.exe`). + +### `VP_VERSION` + +- **Purpose**: Version to install +- **Default**: `latest` +- **CLI equivalent**: `--version` +- **Example**: + + ```bash + # Unix + VP_VERSION=1.2.3 curl -fsSL https://vite.plus | bash + ``` + + ```powershell + # PowerShell + $env:VP_VERSION = "1.2.3"; irm https://vite.plus/ps1 | iex + ``` + +### `VP_HOME` + +- **Purpose**: Installation directory +- **Default**: `~/.vite-plus` (Unix) or `%USERPROFILE%\.vite-plus` (Windows) +- **CLI equivalent**: `--install-dir` +- **Example**: + + ```bash + # Unix + VP_HOME=/opt/vite-plus curl -fsSL https://vite.plus | bash + ``` + + ```powershell + # PowerShell + $env:VP_HOME = "D:\vite-plus"; irm https://vite.plus/ps1 | iex + ``` + +### `NPM_CONFIG_REGISTRY` + +- **Purpose**: Custom npm registry URL +- **Default**: `https://registry.npmjs.org` +- **CLI equivalent**: `--registry` +- **Example**: + ```bash + NPM_CONFIG_REGISTRY=https://registry.npmmirror.com curl -fsSL https://vite.plus | bash + ``` + +### `VP_NODE_MANAGER` + +- **Purpose**: Control Node.js version manager setup during installation +- **Values**: `yes` or `no` +- **Default**: Auto-detected based on environment +- **CLI equivalent**: `--no-node-manager` (inverted) +- **Example**: + ```bash + # Skip Node.js manager setup in CI + VP_NODE_MANAGER=no curl -fsSL https://vite.plus | bash + ``` + +### `VP_PR_VERSION` + +- **Purpose**: Install a preview build from a pull request or commit SHA +- **Values**: PR number or commit SHA +- **Default**: None +- **Example**: + ```bash + # Install preview build for PR #1569 + VP_PR_VERSION=1569 curl -fsSL https://vite.plus | bash + ``` + +### `VP_LOCAL_TGZ` + +- **Purpose**: Path to local `vite-plus.tgz` for development/testing +- **Default**: None +- **Example**: + ```bash + VP_LOCAL_TGZ=./vite-plus-0.0.0.tgz curl -fsSL https://vite.plus | bash + ``` + +### `VP_LOCAL_BINARY` + +- **Purpose**: Path to local `vp` binary for development +- **Default**: None +- **Note**: Set by `install-global-cli.ts` for local development + +### Internal (do not set manually) + +These variables are used internally by the installers and should not be set manually: + +- `VP_INSTALL_STOP` — Signal to stop installation (used internally by `install.ps1`) + +## Runtime Variables + +These variables affect the behavior of the installed Vite+ CLI. + +### `VP_HOME` + +- **Purpose**: Override the Vite+ home directory +- **Default**: `~/.vite-plus` +- **Example**: + ```bash + export VP_HOME=/opt/vite-plus + ``` + +### `VP_NODE_DIST_MIRROR` + +- **Purpose**: Node.js distribution mirror URL +- **Default**: `https://nodejs.org/dist` +- **Example**: + ```bash + export VP_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node + ``` + +### `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 + ``` + + ```cmd + :: CMD + set VP_NODE_VERSION=22 && vp env exec node -v + ``` + +### `VP_NODE_SKIP_SIGNATURE_VERIFY` + +- **Purpose**: Skip PGP signature verification of Node.js downloads +- **Values**: Any non-empty value +- **Default**: None (verification enabled) +- **Example**: + ```bash + VP_NODE_SKIP_SIGNATURE_VERIFY=1 vp env install 22 + ``` + +### `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 + ``` + +### `VP_ENV_USE_EVAL_ENABLE` + +- **Purpose**: Enable eval mode for `vp env use` +- **Values**: Any non-empty value +- **Default**: None +- **Example**: + ```bash + VP_ENV_USE_EVAL_ENABLE=1 eval "$(vp env use 20)" + ``` + +### `VP_SHELL` + +- **Purpose**: Explicitly specify the current shell +- **Default**: Auto-detected +- **Example**: + ```bash + VP_SHELL=bash vp env print + ``` + +### `VP_BYPASS` + +- **Purpose**: Bypass Vite+ shim and use system tool directly +- **Values**: `PATH`-style list of directories to bypass +- **Default**: None +- **Example**: + ```bash + VP_BYPASS=/usr/local/bin node -v + ``` + +### Internal (do not set manually) + +These variables are set automatically by Vite+ during runtime and should not be configured manually: + +- `VP_TOOL_RECURSION` — Recursion guard for `vp env exec` (prevents infinite shim loops) +- `VP_ACTIVE_NODE` — Records the active Node.js version (set by shim dispatch) +- `VP_RESOLVE_SOURCE` — Records how the Node.js version was resolved (set by shim dispatch) +- `VP_SHIM_TOOL` — Indicates which tool is being shimmed (set by shell wrapper scripts) +- `VP_SHIM_WRAPPER` — Windows shim wrapper flag (set by Windows shim wrappers) +- `VP_CLI_BIN` — Path to the `vp` binary (passed to JS scripts for CLI commands) +- `VP_GLOBAL_VERSION` — Global CLI version (passed from Rust binary to JS for `--version` display) + +## TLS/CA Configuration + +### `SSL_CERT_FILE` + +- **Purpose**: Path to PEM bundle of extra CA certificates +- **Default**: System trust store +- **Example**: + ```bash + export SSL_CERT_FILE=/path/to/custom-ca.pem + ``` + +### `NODE_EXTRA_CA_CERTS` + +- **Purpose**: Path to PEM bundle of extra CA certificates (Node.js convention) +- **Default**: System trust store +- **Example**: + ```bash + export NODE_EXTRA_CA_CERTS=/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. The effect is limited to the current process/command only; remove the variable immediately after troubleshooting. +- **Example**: + + ```bash + VP_INSECURE_TLS=1 vp env install 22 + ``` + + ```cmd + :: CMD + set VP_INSECURE_TLS=1 && vp env install 22 + ``` + +## Logging and Debugging + +### `VITE_LOG` + +- **Purpose**: Log filter string for `tracing_subscriber` +- **Default**: None +- **Example**: + ```bash + VITE_LOG=debug vp dev + VITE_LOG=vite_task=trace vp build + ``` + +### `VITE_UPDATE_TASK_TYPES` + +- **Purpose**: Filter for update task types +- **Default**: None +- **Example**: + ```bash + VITE_UPDATE_TASK_TYPES=dependencies vp update + ``` + +### `VITE_GLOBAL_CLI_JS_SCRIPTS_DIR` + +- **Purpose**: Override directory for global CLI JS scripts +- **Default**: Auto-detected +- **Example**: + ```bash + VITE_GLOBAL_CLI_JS_SCRIPTS_DIR=/path/to/scripts vp help + ``` + +## Testing/Development + +### `VP_TRAMPOLINE_PATH` + +- **Purpose**: Override trampoline binary path for tests +- **Default**: Auto-detected from `current_exe()` +- **Example**: + ```bash + VP_TRAMPOLINE_PATH=/path/to/trampoline vp setup + ``` + +## 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**: Used to resolve `~/.vite-plus` default path + +## 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` will install version 2.0.0. diff --git a/docs/guide/upgrade.md b/docs/guide/upgrade.md index 647e865c9e..a6483234d9 100644 --- a/docs/guide/upgrade.md +++ b/docs/guide/upgrade.md @@ -88,6 +88,10 @@ Remove-Item Env:\VP_PR_VERSION The installer resolves the ref to its `0.0.0-commit.` build through the registry bridge and installs it like any other version. Run `vp --version` afterward to confirm which build and bundled tool versions are active. When you are done testing, return to the published release with `vp upgrade --force` or by running the installer again without `VP_PR_VERSION`. +::: tip +See the [Installer Environment Variables](/guide/installer-env-vars) page for all available environment variables. +::: + ### Local `vite-plus` Preview After installing the preview global CLI above, run migrate in the project to move its local `vite-plus` onto the same build: From c7ba39f260d96b2c591c00d5b1e1b0325eb47c4d Mon Sep 17 00:00:00 2001 From: yukinoshi <9241225+yukionno@user.noreply.gitee.com> Date: Thu, 9 Jul 2026 23:59:53 +0800 Subject: [PATCH 2/3] clear no need hint and vars to bash, not curl --- docs/guide/docker.md | 2 +- docs/guide/env.md | 4 ---- docs/guide/install.md | 4 ---- docs/guide/installer-env-vars.md | 12 ++++++------ docs/guide/upgrade.md | 4 ---- 5 files changed, 7 insertions(+), 19 deletions(-) diff --git a/docs/guide/docker.md b/docs/guide/docker.md index d1b3b9abe4..57732771d5 100644 --- a/docs/guide/docker.md +++ b/docs/guide/docker.md @@ -216,4 +216,4 @@ docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp bui 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). See the [Installer Environment Variables](/guide/installer-env-vars) page for all available options. + version). diff --git a/docs/guide/env.md b/docs/guide/env.md index 302270af29..2abd62fb3d 100644 --- a/docs/guide/env.md +++ b/docs/guide/env.md @@ -2,10 +2,6 @@ `vp env` manages Node.js versions globally and per project. -::: info -For environment variables recognized by the installer scripts (`install.ps1`, `install.sh`) and `vp-setup.exe`, see the [Installer Environment Variables](/guide/installer-env-vars) page. -::: - ## Overview Managed mode is on by default, so `node`, `npm`, and related shims resolve through Vite+ and pick the right Node.js version for the current project. diff --git a/docs/guide/install.md b/docs/guide/install.md index 52d46b59fc..fc0b6f4b54 100644 --- a/docs/guide/install.md +++ b/docs/guide/install.md @@ -2,10 +2,6 @@ `vp install` installs dependencies using the current workspace's package manager. -::: info -For environment variables recognized by the installer scripts (`install.ps1`, `install.sh`) and `vp-setup.exe`, see the [Installer Environment Variables](/guide/installer-env-vars) page. -::: - ## Overview Use Vite+ to manage dependencies across pnpm, npm, Yarn, and Bun. Instead of switching between `pnpm install`, `npm install`, `yarn install`, and `bun install`, you can keep using `vp install`, `vp add`, `vp remove`, and the rest of the Vite+ package-management commands. diff --git a/docs/guide/installer-env-vars.md b/docs/guide/installer-env-vars.md index cfe08559da..dfd9095ae5 100644 --- a/docs/guide/installer-env-vars.md +++ b/docs/guide/installer-env-vars.md @@ -19,7 +19,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan ```bash # Unix - VP_VERSION=1.2.3 curl -fsSL https://vite.plus | bash + curl -fsSL https://vite.plus | VP_VERSION=1.2.3 bash ``` ```powershell @@ -36,7 +36,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan ```bash # Unix - VP_HOME=/opt/vite-plus curl -fsSL https://vite.plus | bash + curl -fsSL https://vite.plus | VP_HOME=/opt/vite-plus bash ``` ```powershell @@ -51,7 +51,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan - **CLI equivalent**: `--registry` - **Example**: ```bash - NPM_CONFIG_REGISTRY=https://registry.npmmirror.com curl -fsSL https://vite.plus | bash + curl -fsSL https://vite.plus | NPM_CONFIG_REGISTRY=https://registry.npmmirror.com bash ``` ### `VP_NODE_MANAGER` @@ -63,7 +63,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan - **Example**: ```bash # Skip Node.js manager setup in CI - VP_NODE_MANAGER=no curl -fsSL https://vite.plus | bash + curl -fsSL https://vite.plus | VP_NODE_MANAGER=no bash ``` ### `VP_PR_VERSION` @@ -74,7 +74,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan - **Example**: ```bash # Install preview build for PR #1569 - VP_PR_VERSION=1569 curl -fsSL https://vite.plus | bash + curl -fsSL https://vite.plus | VP_PR_VERSION=1569 bash ``` ### `VP_LOCAL_TGZ` @@ -83,7 +83,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan - **Default**: None - **Example**: ```bash - VP_LOCAL_TGZ=./vite-plus-0.0.0.tgz curl -fsSL https://vite.plus | bash + curl -fsSL https://vite.plus | VP_LOCAL_TGZ=./vite-plus-0.0.0.tgz bash ``` ### `VP_LOCAL_BINARY` diff --git a/docs/guide/upgrade.md b/docs/guide/upgrade.md index a6483234d9..647e865c9e 100644 --- a/docs/guide/upgrade.md +++ b/docs/guide/upgrade.md @@ -88,10 +88,6 @@ Remove-Item Env:\VP_PR_VERSION The installer resolves the ref to its `0.0.0-commit.` build through the registry bridge and installs it like any other version. Run `vp --version` afterward to confirm which build and bundled tool versions are active. When you are done testing, return to the published release with `vp upgrade --force` or by running the installer again without `VP_PR_VERSION`. -::: tip -See the [Installer Environment Variables](/guide/installer-env-vars) page for all available environment variables. -::: - ### Local `vite-plus` Preview After installing the preview global CLI above, run migrate in the project to move its local `vite-plus` onto the same build: From cfb62502d08e023d610cabdeed2e66153319aac0 Mon Sep 17 00:00:00 2001 From: MK Date: Fri, 10 Jul 2026 20:02:35 +0800 Subject: [PATCH 3/3] docs: trim installer env vars page and add sidebar entry - Fix trailing whitespace in docker.md (vp fmt --check failure) - Merge the duplicate VP_HOME entries into one - Link the canonical sections for VP_PR_VERSION, VP_NODE_DIST_MIRROR, and VP_NODE_SKIP_SIGNATURE_VERIFY instead of restating them - Drop VITE_UPDATE_TASK_TYPES (test-time codegen switch; the documented vp update command does not exist), VP_TRAMPOLINE_PATH (test-only), VP_ENV_USE_EVAL_ENABLE and VITE_GLOBAL_CLI_JS_SCRIPTS_DIR (internal/dev) - Compress the internal-variable lists and dev-only installer vars to short notes; merge SSL_CERT_FILE / NODE_EXTRA_CA_CERTS - Register the page in the sidebar next to Environment and replace the Getting Started info box with a plain sentence --- docs/.vitepress/config.mts | 1 + docs/guide/docker.md | 2 +- docs/guide/index.md | 4 +- docs/guide/installer-env-vars.md | 154 +++++-------------------------- 4 files changed, 26 insertions(+), 135 deletions(-) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index eee476b967..2e648a180e 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -35,6 +35,7 @@ const guideSidebar = [ { text: 'Migrate to Vite+', link: '/guide/migrate' }, { 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' }, ], }, diff --git a/docs/guide/docker.md b/docs/guide/docker.md index 57732771d5..204e2294cd 100644 --- a/docs/guide/docker.md +++ b/docs/guide/docker.md @@ -216,4 +216,4 @@ docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp bui 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). + version). diff --git a/docs/guide/index.md b/docs/guide/index.md index cf1f047768..6d76c9a69e 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -28,9 +28,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"**. ::: -::: info Installer Environment Variables -The installer scripts and `vp-setup.exe` support environment variables for customization. See the [Installer Environment Variables](/guide/installer-env-vars) page for details. -::: +The installer scripts and `vp-setup.exe` read [environment variables](/guide/installer-env-vars) such as `VP_VERSION` and `VP_HOME`. After installation, open a new shell and run: diff --git a/docs/guide/installer-env-vars.md b/docs/guide/installer-env-vars.md index dfd9095ae5..592419ceb1 100644 --- a/docs/guide/installer-env-vars.md +++ b/docs/guide/installer-env-vars.md @@ -1,14 +1,10 @@ # Installer Environment Variables -This page documents all environment variables recognized by the Vite+ installers (`vp-setup.exe`, `install.ps1`, and `install.sh`). - -::: tip -The set of supported variables may change between releases. Always check the [release notes](https://github.com/voidzero-dev/vite-plus/releases) for the version you are using. -::: +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 behavior of the Vite+ installer scripts and the standalone Windows installer (`vp-setup.exe`). +These variables control the installer scripts and the standalone Windows installer (`vp-setup.exe`). ### `VP_VERSION` @@ -29,7 +25,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan ### `VP_HOME` -- **Purpose**: Installation directory +- **Purpose**: Installation directory; the installed CLI reads the same variable as the Vite+ home directory (see [Environment](/guide/env)) - **Default**: `~/.vite-plus` (Unix) or `%USERPROFILE%\.vite-plus` (Windows) - **CLI equivalent**: `--install-dir` - **Example**: @@ -58,7 +54,7 @@ These variables control the behavior of the Vite+ installer scripts and the stan - **Purpose**: Control Node.js version manager setup during installation - **Values**: `yes` or `no` -- **Default**: Auto-detected based on environment +- **Default**: Auto-detected - **CLI equivalent**: `--no-node-manager` (inverted) - **Example**: ```bash @@ -71,104 +67,42 @@ These variables control the behavior of the Vite+ installer scripts and the stan - **Purpose**: Install a preview build from a pull request or commit SHA - **Values**: PR number or commit SHA - **Default**: None -- **Example**: - ```bash - # Install preview build for PR #1569 - curl -fsSL https://vite.plus | VP_PR_VERSION=1569 bash - ``` +- **Details**: [Global `vp` Preview](/guide/upgrade#global-vp-preview) -### `VP_LOCAL_TGZ` - -- **Purpose**: Path to local `vite-plus.tgz` for development/testing -- **Default**: None -- **Example**: - ```bash - curl -fsSL https://vite.plus | VP_LOCAL_TGZ=./vite-plus-0.0.0.tgz bash - ``` +### Development variables -### `VP_LOCAL_BINARY` - -- **Purpose**: Path to local `vp` binary for development -- **Default**: None -- **Note**: Set by `install-global-cli.ts` for local development - -### Internal (do not set manually) - -These variables are used internally by the installers and should not be set manually: - -- `VP_INSTALL_STOP` — Signal to stop installation (used internally by `install.ps1`) +When developing Vite+ itself, `VP_LOCAL_TGZ` (path to a local `vite-plus.tgz`) and `VP_LOCAL_BINARY` (path to a local `vp` binary) feed the installer a local build. The installers also set `VP_INSTALL_STOP` themselves; do not set it manually. ## Runtime Variables -These variables affect the behavior of the installed Vite+ CLI. - -### `VP_HOME` - -- **Purpose**: Override the Vite+ home directory -- **Default**: `~/.vite-plus` -- **Example**: - ```bash - export VP_HOME=/opt/vite-plus - ``` +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` -- **Example**: - ```bash - export VP_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node - ``` +- **Details**: [Custom Node.js Mirror](/guide/env#custom-nodejs-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 ``` - ```cmd - :: CMD - set VP_NODE_VERSION=22 && vp env exec node -v - ``` - ### `VP_NODE_SKIP_SIGNATURE_VERIFY` - **Purpose**: Skip PGP signature verification of Node.js downloads - **Values**: Any non-empty value - **Default**: None (verification enabled) -- **Example**: - ```bash - VP_NODE_SKIP_SIGNATURE_VERIFY=1 vp env install 22 - ``` - -### `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 - ``` - -### `VP_ENV_USE_EVAL_ENABLE` - -- **Purpose**: Enable eval mode for `vp env use` -- **Values**: Any non-empty value -- **Default**: None -- **Example**: - ```bash - VP_ENV_USE_EVAL_ENABLE=1 eval "$(vp env use 20)" - ``` +- **Details**: [Node.js Signature Verification](/guide/env#nodejs-signature-verification) ### `VP_SHELL` -- **Purpose**: Explicitly specify the current shell +- **Purpose**: Specify the current shell - **Default**: Auto-detected - **Example**: ```bash @@ -177,7 +111,7 @@ These variables affect the behavior of the installed Vite+ CLI. ### `VP_BYPASS` -- **Purpose**: Bypass Vite+ shim and use system tool directly +- **Purpose**: Bypass the Vite+ shim and use the system tool - **Values**: `PATH`-style list of directories to bypass - **Default**: None - **Example**: @@ -185,55 +119,32 @@ These variables affect the behavior of the installed Vite+ CLI. VP_BYPASS=/usr/local/bin node -v ``` -### Internal (do not set manually) - -These variables are set automatically by Vite+ during runtime and should not be configured manually: +### Internal variables -- `VP_TOOL_RECURSION` — Recursion guard for `vp env exec` (prevents infinite shim loops) -- `VP_ACTIVE_NODE` — Records the active Node.js version (set by shim dispatch) -- `VP_RESOLVE_SOURCE` — Records how the Node.js version was resolved (set by shim dispatch) -- `VP_SHIM_TOOL` — Indicates which tool is being shimmed (set by shell wrapper scripts) -- `VP_SHIM_WRAPPER` — Windows shim wrapper flag (set by Windows shim wrappers) -- `VP_CLI_BIN` — Path to the `vp` binary (passed to JS scripts for CLI commands) -- `VP_GLOBAL_VERSION` — Global CLI version (passed from Rust binary to JS for `--version` display) +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` +### `SSL_CERT_FILE` / `NODE_EXTRA_CA_CERTS` -- **Purpose**: Path to PEM bundle of extra CA certificates +- **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 ``` -### `NODE_EXTRA_CA_CERTS` - -- **Purpose**: Path to PEM bundle of extra CA certificates (Node.js convention) -- **Default**: System trust store -- **Example**: - ```bash - export NODE_EXTRA_CA_CERTS=/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. The effect is limited to the current process/command only; remove the variable immediately after troubleshooting. +- **Warning**: Diagnostic escape hatch only; do not use in production - **Example**: - ```bash VP_INSECURE_TLS=1 vp env install 22 ``` - ```cmd - :: CMD - set VP_INSECURE_TLS=1 && vp env install 22 - ``` - ## Logging and Debugging ### `VITE_LOG` @@ -246,33 +157,14 @@ These variables are set automatically by Vite+ during runtime and should not be VITE_LOG=vite_task=trace vp build ``` -### `VITE_UPDATE_TASK_TYPES` +### `VP_DEBUG_SHIM` -- **Purpose**: Filter for update task types +- **Purpose**: Enable debug output for shim dispatch +- **Values**: Any non-empty value - **Default**: None - **Example**: ```bash - VITE_UPDATE_TASK_TYPES=dependencies vp update - ``` - -### `VITE_GLOBAL_CLI_JS_SCRIPTS_DIR` - -- **Purpose**: Override directory for global CLI JS scripts -- **Default**: Auto-detected -- **Example**: - ```bash - VITE_GLOBAL_CLI_JS_SCRIPTS_DIR=/path/to/scripts vp help - ``` - -## Testing/Development - -### `VP_TRAMPOLINE_PATH` - -- **Purpose**: Override trampoline binary path for tests -- **Default**: Auto-detected from `current_exe()` -- **Example**: - ```bash - VP_TRAMPOLINE_PATH=/path/to/trampoline vp setup + VP_DEBUG_SHIM=1 node -v ``` ## Standard Environment Variables @@ -292,7 +184,7 @@ Vite+ also respects these standard environment variables: ### `HOME` / `USERPROFILE` - **Purpose**: User home directory -- **Effect**: Used to resolve `~/.vite-plus` default path +- **Effect**: Base for the default `~/.vite-plus` path ## Precedence @@ -300,4 +192,4 @@ Vite+ also respects these standard environment variables: 2. Environment variables 3. Default values (lowest priority) -For example, `VP_VERSION=1.0.0 vp-setup.exe --version 2.0.0` will install version 2.0.0. +For example, `VP_VERSION=1.0.0 vp-setup.exe --version 2.0.0` installs version 2.0.0.