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

• Example:

  # Unix
  curl -fsSL https://vite.plus | VP_VERSION=1.2.3 bash

  # PowerShell
  $env:VP_VERSION = "1.2.3"; irm https://vite.plus/ps1 | iex

VP_HOME

• Purpose: Installer-only override that selects the legacy monolithic layout, rooted at the given directory

• Default: None — fresh installs use the split layout; ~/.vite-plus is used only when it already exists (grandfathered installs) or when VP_HOME/--install-dir is set

• CLI equivalent: --install-dir

• Details: Only the installers (install.sh, install.ps1, vp-setup.exe) read VP_HOME; the installed vp CLI never does. At runtime the CLI locates a custom install root from the vp binary's own path (<root>/current/bin/vp), so installs at a custom VP_HOME keep working without any variable set. See Directory Layout and XDG Variables.

• Example:

  # Unix
  curl -fsSL https://vite.plus | VP_HOME=/opt/vite-plus bash

  # 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:

  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:

  # Skip Node.js manager setup in CI
  curl -fsSL https://vite.plus | VP_NODE_MANAGER=no bash

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

Development variables

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 configure the installed Vite+ CLI.

VP_BIN_DIR

• Purpose: Directory for executables and shims (node, npm, npx, corepack, vpx, vpr, the vp wrapper)
• Default: XDG_BIN_HOME if set, then XDG_DATA_HOME/../bin, otherwise ~/.local/bin (Unix) or %LOCALAPPDATA%\vite-plus\bin (Windows)
• Details: Only applies in the split layout; ignored when the legacy monolithic layout is selected. See Directory Layout and XDG Variables.

VP_DATA_DIR

• Purpose: Payload data directory (CLI versions, managed Node.js runtimes, package managers, global packages)
• Default: XDG_DATA_HOME/vite-plus if set, otherwise ~/.local/share/vite-plus (Unix) or %LOCALAPPDATA%\vite-plus\data (Windows)
• Details: Only applies in the split layout; ignored when the legacy monolithic layout is selected. See Directory Layout and XDG Variables.

VP_CACHE_DIR

• Purpose: Disposable cache directory
• Default: XDG_CACHE_HOME/vite-plus if set, otherwise ~/.cache/vite-plus (Unix) or %LOCALAPPDATA%\vite-plus\cache (Windows)
• Details: Only applies in the split layout; ignored when the legacy monolithic layout is selected. See Directory Layout and XDG Variables.

VP_NODE_DIST_MIRROR

• Purpose: Node.js distribution mirror URL
• Default: https://nodejs.org/dist
• Details: Custom Node.js Mirror

VP_NODE_VERSION

• Purpose: Override Node.js version
• Default: None (auto-detected)
• Example:

  # Run a command with a specific Node.js version
  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)
• Details: Node.js Signature Verification

VP_SHELL

• Purpose: Specify the current shell
• Default: Auto-detected
• Example:

  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:

  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:

  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:

  VP_INSECURE_TLS=1 vp env install 22

Logging and Debugging

VP_LOG

• Purpose: Log filter string for tracing_subscriber
• Default: None
• Example:

  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:

  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 legacy ~/.vite-plus root and the Unix platform defaults (~/.local/bin, ~/.config, ...)

XDG_BIN_HOME / XDG_CONFIG_HOME / XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME

• Purpose: XDG base directories honored when resolving the split layout
• Details: Read directly from the process environment during directory resolution. See Directory Layout and XDG Variables.

Directory Layout and XDG Variables

The installed CLI resolves where its files live by picking one of two layouts; the first match wins:

1. Executable self-location — the running vp binary's own (canonicalized) path matches <X>/current/bin/vp: when <X>/bin/vp also exists, <X> is a legacy monolithic install root; otherwise <X> is the data dir of a split install, and the data category is pinned to it (the other categories resolve through their normal chains). This covers custom-location installs (previously located via VP_HOME) and launches without PATH context (IDEs, the Windows shim trampoline).
2. PATH inference — for a PATH entry containing a vp executable: a <root>/bin entry with the legacy layout (bin/vp plus current/bin/vp) marks <root> as a legacy install; otherwise the entry's vp is canonicalized and, when it resolves into <X>/current/bin/vp, the same legacy-vs-split rule as rule 1 applies.
3. ~/.vite-plus exists — the legacy monolithic layout, grandfathered: existing installs keep working untouched and nothing is moved.
4. Otherwise (fresh installs) — a split layout where each category resolves independently through its own override → XDG → platform-default chain:

Category	Contents	Resolution (first match wins)	Unix default	Windows default
Executables and shims	node, npm, npx, corepack, vpx, vpr, the vp wrapper	VP_BIN_DIR → XDG_BIN_HOME → XDG_DATA_HOME/../bin	~/.local/bin	%LOCALAPPDATA%\vite-plus\bin
Configuration	config.json, shell env scripts	XDG_CONFIG_HOME/vite-plus	~/.config/vite-plus	%APPDATA%\vite-plus
Data	CLI versions, managed Node.js runtimes, package managers, global packages, per-binary bins/*.json metadata	VP_DATA_DIR → XDG_DATA_HOME/vite-plus	~/.local/share/vite-plus	%LOCALAPPDATA%\vite-plus\data
State	Session and upgrade-check files	XDG_STATE_HOME/vite-plus	~/.local/state/vite-plus	%LOCALAPPDATA%\vite-plus\state
Cache	Disposable caches	VP_CACHE_DIR → XDG_CACHE_HOME/vite-plus	~/.cache/vite-plus	%LOCALAPPDATA%\vite-plus\cache

Notes:

• Relative values in the VP_*_DIR and XDG_* variables are ignored, per the XDG Base Directory specification.
• VP_BIN_DIR, VP_DATA_DIR, and VP_CACHE_DIR only apply in the split layout; the legacy layout is all-or-nothing.
• The CLI never reads VP_HOME; rules 1–2 replace it. VP_HOME remains an installer-only override that selects the legacy monolithic layout at install time.
• The installers (install.sh, install.ps1, vp-setup.exe) default to the split layout for fresh installs; an existing ~/.vite-plus keeps the legacy layout.

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.