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. It belongs to the 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.

Use vp env off to disable managed mode for Node.js and package managers. See 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.

Unqualified versions remain Node.js versions for compatibility:

vp env pin 22.0.0               # Node.js only
vp env pin pnpm@10.18.0         # pnpm only
vp env pin node@24 pnpm@12      # Both components
vp env pin 22.0.0 pnpm@10.18.0  # Also both components

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)
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.

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.

Using pnpm with Vite+ runtime management

pnpm can also manage the runtime declared in devEngines.runtime. When both pnpm and Vite+ manage Node.js, they can download the same version separately or select different versions, causing inconsistent behavior between commands.

If you want Vite+ to manage Node.js, pnpm 11+ supports disabling pnpm's automatic runtime management globally with runtimeOnFail:

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
2. VP_PACKAGE_MANAGER
3. Top-level packageManager
4. devEngines.packageManager
5. Lockfile or manager-specific configuration
6. The named package manager's global default version
7. The named shim's latest release

VP_PACKAGE_MANAGER selects the manager and version for commands such as vp install. Direct package-manager shims ignore this variable and use independent version overrides:

Variable	Shims
VP_NPM_VERSION	npm, npx
VP_PNPM_VERSION	pnpm, pnpx
VP_YARN_VERSION	yarn, yarnpkg
VP_BUN_VERSION	bun, bunx

These variables accept a version or range, such as 10.18.0, 10, or latest, and override the matching shim's project and default versions. They do not change the manager or version selected by vp install.

vp env use pnpm@10.20.0 sets VP_PNPM_VERSION for the current shell, just as vp env use node@22 sets VP_NODE_VERSION. Each package manager has its own override, so switching Yarn does not clear a pnpm override. vp env use does not set or clear VP_PACKAGE_MANAGER.

Direct shims resolve their version from the matching environment variable, then the matching session file when no shell wrapper is available, then project configuration and the family default. vp env current pnpm and vp env which pnpm inspect this shim selection; vp env current pm reports the manager selected for vp commands.

VP_PACKAGE_MANAGER=pnpm@10.18.0 vp install
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 directly invoked npm shim keeps its Node-bundled fallback, while an explicit vp env ... npm family scope uses standalone npm's latest release.

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.

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.

To enable managed mode, run:

vp env on

This enables managed mode for both components. Their modes can also be changed independently, including one package-manager family:

vp env on node
vp env off pm
vp env off pnpm
vp env on bun

If you do not want Vite+ to manage Node.js first, run:

vp env off

This switches both components to system-first mode. Vite+ prefers system tools and falls back to managed installations. Mixed configurations compose: a system package-manager launcher receives the Node.js selected by the Node mode.

Using pm records the selected mode for all currently supported package managers and replaces their individual choices. An unscoped on or off does the same while also changing Node.js. A family without a recorded mode remains undecided until its shim is first used or an on / off command configures it.

Commands

Setup

• vp env setup creates or updates the node, npm, npx, pnpm, pnpx, yarn, yarnpkg, bun, bunx, vpx, and vpr shims in the resolved bin directory. It writes shell setup scripts in the config directory.
• vp env on / vp env off changes both modes; append node, pm, npm, pnpm, yarn, or bun to narrow the change
• vp env print prints PATH setup for both components; append a selector to print one

PowerShell needs to dot-source the generated setup script in the current shell before vp env use can affect only that shell session:

. "$env:APPDATA\vite-plus\env.ps1"

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.

Create the profile file if it does not already exist:

if (-not (Test-Path $PROFILE)) { New-Item $PROFILE -Force }

Open the profile file for editing:

Invoke-Item $PROFILE

Windows Command Prompt (cmd.exe) cannot define the wrapper function needed for vp env use to update the current shell session. Use the generated vp-use.cmd command instead:

vp-use 20
node --version
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.

Manage

• vp env default shows the global Node.js default and each configured package-manager version. Bare versions set Node.js; qualified specs such as pnpm@10.18.0 set that package manager's shim default without replacing the defaults for Bun, Yarn, or npm. --unset clears all defaults unless scoped.
• vp env pin shows or writes project pins. Existing .node-version and top-level packageManager fields keep being updated for compatibility. An existing .nvmrc is updated when it is the effective Node source in the current directory; its comments and other non-version content are preserved. Otherwise Vite+ writes the matching devEngines entry. Use --target node-version, --target nvmrc, --target dev-engines, or --target package-manager to choose explicitly. Pinning in a child directory does not modify an inherited .nvmrc.
• vp env unpin removes both effective pins by default; append a selector to remove one. Lower-priority declarations are not deleted.
• vp env use activates the complete project environment. Explicit specs override selected components; --unset clears both unless scoped.
• vp env install installs the complete resolved environment, a selected component, or explicit specs.
• vp env uninstall removes explicit exact Node.js or qualified package-manager versions.
• vp env clean removes unused installs. Use clean node, clean pm, or a concrete manager. Current and configured-default versions are preserved.
• vp env exec runs a command in the resolved environment. Use --node and --package-manager; --npm is an alias for --package-manager npm@….
• vp node uses the resolved Node.js runtime and exposes the selected package-manager path to child processes.

Inspect

• vp env current shows the current resolved environment
• vp env doctor runs environment diagnostics
• vp env which shows which tool path will be used
• vp env list shows separate Node.js, npm, pnpm, Yarn, and Bun sections; selectors narrow output
• vp env list-remote fetches Node.js and all four PM registries concurrently; selectors narrow network work. --lts implicitly selects Node.js.

Project Setup

• Pin a project version with vp env pin
• Use vp install, vp dev, and vp build normally
• Let Vite+ pick the right runtime for the project

Examples

# Setup
vp env setup                  # Create Node.js and package-manager shims
vp env on                     # Manage Node.js and package managers
vp env off pm                 # Prefer system package managers only
vp env off pnpm               # Prefer system pnpm only
vp env print                  # Print PATH setup for both components

# Manage
vp env pin lts pnpm@10        # Pin both project components to exact versions
vp env install                # Install the complete resolved environment
vp env default node@24        # Set the global Node.js default
vp env default pnpm@10        # Set pnpm's global default version
vp env use 20 pnpm@10         # Override both components for this shell
vp env use --unset pnpm       # Remove only the pnpm session version
vp env use --unset pm         # Remove all package-manager session versions
vp env clean                  # Remove unused managed Node.js and package manager versions

# Inspect
vp env current                # Show current resolved environment
vp env current --json         # JSON output for automation
vp env which node             # Show which node binary will be used
vp env which npx              # Show pinned package-manager alias when packageManager matches
vp env list                   # Show every locally installed component
vp env list node              # Show only Node.js installations
vp env list-remote --lts      # List only Node.js LTS versions

# Execute
vp env exec --node lts --package-manager pnpm@10 pnpm install
vp env exec node -v           # Use shim mode with automatic version resolution
vp node script.js             # Shorthand: run a Node.js script with the resolved version
vp node -e "console.log(1+1)" # Shorthand: forward any node flag or argument

JSON output

The JSON output for current, list, and list-remote is organized by component. current --json returns sibling node and package_manager objects:

{
  "node": {
    "version": "22.0.0",
    "source": "devEngines.runtime",
    "source_path": "/project/package.json",
    "project_root": "/project",
    "bin_path": "/home/.vite-plus/js_runtime/node/22.0.0/bin/node",
    "installed": true,
    "mode": "managed"
  },
  "package_manager": {
    "name": "pnpm",
    "version": "10.18.0",
    "source": "packageManager",
    "source_path": "/project/package.json",
    "project_root": "/project",
    "bin_paths": {
      "pnpm": "/home/.vite-plus/package_manager/pnpm/10.18.0/pnpm/bin/pnpm",
      "pnpx": "/home/.vite-plus/package_manager/pnpm/10.18.0/pnpm/bin/pnpx"
    },
    "installed": true,
    "mode": "managed"
  }
}

list --json and list-remote --json group the component arrays:

{
  "node": [],
  "package_managers": {
    "npm": [],
    "pnpm": [],
    "yarn": [],
    "bun": []
  }
}

Selectors omit unselected top-level fields or PM families. Registry listing is all-or-error: Vite+ prints no partial human or JSON result when any selected registry request fails.

Custom Node.js Mirror

By default, Vite+ downloads Node.js from https://nodejs.org/dist. If you're behind a corporate proxy or need to use an internal mirror (e.g., Artifactory), set the VP_NODE_DIST_MIRROR environment variable:

# Install a specific version from your custom mirror
VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist vp env install 22

# Set the global default version using a custom mirror
VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist vp env default lts

# Set it permanently in your shell profile (.bashrc, .zshrc, etc.)
echo 'export VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist' >> ~/.zshrc

Node.js Signature Verification

When installing Node.js from the official nodejs.org distribution, Vite+ downloads the PGP-signed SHASUMS256.txt.asc and verifies it against the bundled Node.js release keys before trusting any checksum. This protects against a tampered SHASUMS256.txt paired with a matching malicious archive. The SHA-256 checksum of the downloaded archive is always verified afterward.

Custom mirrors (VP_NODE_DIST_MIRROR) that publish only the plain SHASUMS256.txt fall back to checksum-only verification. A mirror that does publish a .asc still has its signature verified, and an invalid signature is a hard error.

If a future keyring or certificate issue blocks downloads, set VP_NODE_SKIP_SIGNATURE_VERIFY to temporarily bypass PGP verification. The SHA-256 checksum is still verified, and Vite+ prints a warning when the signature check is skipped:

VP_NODE_SKIP_SIGNATURE_VERIFY=1 vp env install 22