vite-plus 0.2.4 → 0.2.5

package/docs/guide/docker.md

@@ -30,7 +30,9 @@ Tags track the `vp` 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 a non-root user by default.
+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).
 
@@ -136,6 +138,44 @@ build:
 
 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:
+
+```yaml [.gitlab-ci.yml]
+test:
+  image: ghcr.io/voidzero-dev/vite-plus:latest
+  script:
+    - vp install --frozen-lockfile
+    - vp exec playwright install --with-deps chromium
+    - 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.
+
+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
+WORKDIR /app
+COPY --chown=vp:vp package.json pnpm-lock.yaml pnpm-workspace.yaml .node-version* ./
+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).
+
 ## Devcontainers
 
 Use the image as a ready-to-go development container with the toolchain
@@ -164,7 +204,11 @@ docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp bui
   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).
+  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`.

package/docs/guide/env.md

@@ -64,6 +64,16 @@ 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:
+
+```batch
+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` under `VP_HOME/bin` on Windows.
+
 In CI, `vp env use` can still run without shell initialization. It writes a temporary session file under `VP_HOME` so later shim calls in the same job can resolve the selected Node.js version.
 
 ### Manage
@@ -74,6 +84,7 @@ In CI, `vp env use` can still run without shell initialization. It writes a temp
 - `vp env use` sets a Node.js version for the current shell session
 - `vp env install` installs a Node.js version
 - `vp env uninstall` removes an installed Node.js version
+- `vp env clean` removes unused managed Node.js runtimes, all downloaded package managers, and the Corepack cache.
 - `vp env exec` runs a command with a specific Node.js version
 - `vp node` runs a Node.js script — shorthand for `vp env exec node`
 
@@ -105,6 +116,7 @@ vp env install                # Install the version from .node-version or packag
 vp env default lts            # Set the global default version
 vp env use 20                 # Use Node.js 20 for the current shell session
 vp env use --unset            # Remove the session override
+vp env clean                  # Remove unused managed caches
 
 # Inspect
 vp env current                # Show current resolved environment

package/docs/guide/index.md

@@ -28,6 +28,8 @@ 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`.
+
 After installation, open a new shell and run:
 
 ```bash

package/docs/guide/installer-env-vars.md

@@ -0,0 +1,195 @@
+# 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**:
+
+  ```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**: 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**:
+
+  ```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
+  ```
+
+### `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_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
+
+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_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-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
+  ```
+
+### `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#nodejs-signature-verification)
+
+### `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
+
+### `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
+  ```
+
+### `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 default `~/.vite-plus` 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` installs version 2.0.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plus",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "The Unified Toolchain for the Web",
   "homepage": "https://viteplus.dev/guide",
   "bugs": {
@@ -352,8 +352,8 @@
     }
   },
   "dependencies": {
-    "@oxc-project/types": "=0.138.0",
-    "@oxlint/plugins": "=1.68.0",
+    "@oxc-project/types": "=0.139.0",
+    "@oxlint/plugins": "=1.73.0",
     "@vitest/browser": "4.1.10",
     "@vitest/browser-preview": "4.1.10",
     "@vitest/expect": "4.1.10",
@@ -363,11 +363,11 @@
     "@vitest/snapshot": "4.1.10",
     "@vitest/spy": "4.1.10",
     "@vitest/utils": "4.1.10",
-    "oxfmt": "=0.57.0",
-    "oxlint": "=1.72.0",
+    "oxfmt": "=0.58.0",
+    "oxlint": "=1.73.0",
     "oxlint-tsgolint": "=0.24.0",
     "vitest": "4.1.10",
-    "@voidzero-dev/vite-plus-core": "0.2.4"
+    "@voidzero-dev/vite-plus-core": "0.2.5"
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.7.2",
@@ -392,13 +392,13 @@
     "picocolors": "^1.1.1",
     "rolldown-plugin-dts": "^0.26.0",
     "semver": "^7.8.0",
-    "tsdown": "^0.22.3",
+    "tsdown": "^0.22.7",
     "validate-npm-package-name": "^7.0.2",
     "yaml": "^2.8.1",
     "zod": "^3.25.76",
-    "@voidzero-dev/vite-plus-prompts": "0.0.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.5",
     "@voidzero-dev/vite-plus-tools": "0.0.0",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4"
+    "@voidzero-dev/vite-plus-prompts": "0.0.0"
   },
   "peerDependencies": {
     "@vitest/browser-playwright": "4.1.10",
@@ -430,22 +430,19 @@
     "node": "^20.19.0 || ^22.18.0 || >=24.11.0"
   },
   "optionalDependencies": {
-    "@voidzero-dev/vite-plus-darwin-arm64": "0.2.4",
-    "@voidzero-dev/vite-plus-darwin-x64": "0.2.4",
-    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.2.4",
-    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.2.4",
-    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.2.4",
-    "@voidzero-dev/vite-plus-linux-x64-musl": "0.2.4",
-    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.2.4",
-    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.2.4"
+    "@voidzero-dev/vite-plus-darwin-arm64": "0.2.5",
+    "@voidzero-dev/vite-plus-darwin-x64": "0.2.5",
+    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.2.5",
+    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.2.5",
+    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.2.5",
+    "@voidzero-dev/vite-plus-linux-x64-musl": "0.2.5",
+    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.2.5",
+    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.2.5"
   },
   "scripts": {
     "build": "oxnode -C dev ./build.ts",
     "build-ts": "oxnode -C dev ./build.ts --skip-native",
     "build-native": "oxnode -C dev ./build.ts --skip-ts",
-    "snap-test": "pnpm snap-test-local && pnpm snap-test-global",
-    "snap-test-local": "tool snap-test",
-    "snap-test-global": "tool snap-test --dir snap-tests-global --bin-dir ~/.vite-plus/bin",
     "publish-native": "node ./publish-native-addons.ts",
     "test": "vitest run"
   }

package/templates/monorepo/_gitignore

@@ -12,6 +12,11 @@ dist
 dist-ssr
 *.local
 
+# dotenv environment variable files
+.env
+.env.*
+!.env.example
+
 # Editor directories and files
 .vscode/*
 !.vscode/settings.json

package/templates/monorepo/_yarnrc.yml

@@ -1,4 +1,4 @@
 nodeLinker: node-modules
 catalog:
   '@types/node': ^24
-  typescript: ^5
+  typescript: ^7.0.0

package/templates/monorepo/pnpm-workspace.yaml

@@ -7,4 +7,4 @@ catalogMode: prefer
 
 catalog:
   '@types/node': ^24
-  typescript: ^5
+  typescript: ^7.0.0