GitHub Action, GitLab CI/CD remote template, and Azure Pipelines step template to set up Vite+ (vp).

• Install Vite+ globally via official install scripts
• GitHub Action: optionally set up a specific Node.js version via vp env use
• GitHub Action: cache project dependencies with auto-detection of lock files
• Optionally run vp install after setup
• Optionally wrap vp install with Socket Firewall Free (sfw) to block malicious dependencies
• Support for all major package managers (npm, pnpm, yarn, bun)
• GitLab CI/CD support through a reusable include:remote template
• Azure Pipelines support through a reusable step template and compiled runtime

Reference this action with an exact release tag, or a commit SHA:

- uses: voidzero-dev/setup-vp@v1.20.0

Releases are listed on the tags page. Renovate and Dependabot can keep a pinned tag up to date.

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      node-version: "lts"

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      node-version-file: ".node-version"

The Vite+ installer enables its own Node.js version manager on CI. When Node.js is managed elsewhere (actions/setup-node, Flox, mise, or the runner image), disable it so vp and its shims use that Node.js:

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-node@v5
    with:
      node-version: 24
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      node-manager: false

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      working-directory: web
      node-version-file: ".nvmrc"
      cache: true
      run-install: true

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      node-version: "lts"
      cache: true
      run-install: true

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      version: "1.2.3"
      node-version: "lts"
      cache: true

Vite+ has built-in managed npm, pnpm, yarn, and bun commands. By default, setup-vp enables these commands automatically in CI. If your project uses an older Vite+ version, upgrade Vite+ to v0.3.1 or later.

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
  - run: pnpm --version

Keep a single source of truth for the Vite+ version by resolving it from the checked-out project instead of duplicating it in the workflow.

By default (when neither version nor version-file is set), the action reads the vite-plus entry from the project's package.json and installs that version. When that entry is a semver range like ^0.2.0 (which can't be installed directly), it is resolved to the exact version recorded in the lockfile (pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json, yarn.lock, or bun.lock; the binary bun.lockb can't be read). It falls back to latest only when nothing pins a resolvable version. So a project that pins vite-plus needs no extra configuration:

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      cache: true

To resolve from a specific file, set version-file explicitly. Like the auto-detect default, an explicit version-file that can't be resolved logs a warning and falls back to latest (it does not fail the run); the warning is worth watching for, since it means the pinned version was not applied:

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      version-file: package.json
      cache: true

When the package.json entry is catalog: / catalog:<name>, it is resolved through the nearest catalog source (searching upward from the manifest), covering every package manager that implements the catalog: protocol:

// package.json
{
  "devDependencies": {
    "vite-plus": "catalog:",
  },
}

• pnpm: pnpm-workspace.yaml

  catalog:
    vite-plus: 0.2.0

• yarn (>= 4.10): .yarnrc.yml

  catalog:
    vite-plus: 0.2.0

• bun: root package.json (catalog/catalogs, top-level or under workspaces)

  {
    "workspaces": {
      "packages": ["packages/*"],
      "catalog": { "vite-plus": "0.2.0" },
    },
  }

For npm (no catalog feature) or any project that pins the version directly, just declare an exact version ("vite-plus": "0.2.0") and it is used as-is.

You can also point version-file straight at pnpm-workspace.yaml or .yarnrc.yml to read its default catalog entry. An explicit version always takes precedence over version-file. A resolved value must be an exact version or dist-tag: when an explicit version-file yields a semver range (e.g. ^0.2.0) or an alias (npm: / git:), it can't be installed directly, so the action warns and falls back to latest. (Auto-detection instead resolves a package.json range through the lockfile, as described above.)

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      node-version: "lts"
      cache: true
      run-install: |
        - cwd: ./packages/app
          args: ['--frozen-lockfile']
        - cwd: ./packages/lib

If your repo has a .npmrc that declares the registry, pass NODE_AUTH_TOKEN via env and let the default vp install run — no registry-url needed. When NODE_AUTH_TOKEN is set, the action auto-generates a matching _authToken entry at $RUNNER_TEMP/.npmrc for each registry declared in your repo .npmrc that doesn't already have one, so your repo .npmrc can stay minimal:

# .npmrc in the repo (auth line not required — action adds it):
#   @myorg:registry=https://npm.pkg.github.com

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      node-version: "lts"
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

If you already have the _authToken line in your repo .npmrc (e.g. for local dev symmetry), that's respected as-is and the action won't overwrite it.

Alternatively, pass registry-url explicitly to bypass the action's repo-level .npmrc detection and auth propagation logic (the package manager may still read the repo .npmrc per its own config resolution):

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      node-version: "lts"
      registry-url: "https://npm.pkg.github.com"
      scope: "@myorg"
      run-install: false
  - run: vp install
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Set sfw: true to wrap vp install with Socket Firewall Free. The action downloads the matching sfw binary from the upstream releases (auto-detected per OS/arch, with musl support on Alpine) and runs sfw vp install … so the underlying npm / pnpm / yarn fetches are inspected before packages are installed. Works on Linux, macOS, and Windows:

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      sfw: true
      run-install: true

sfw is only applied when run-install is enabled; other vp commands (e.g. vp env use, vp --version) run unwrapped.

The action pins the sfw version it downloads so a re-run of the same commit gets the same binary.

The bundled download uses a pinned URL but is not itself SHA-pinned. For workflows that want the sfw binary itself SHA-pinned (so a compromise of the upstream release artifact cannot land silently on the next run), compose with socketdev/action in an earlier step. setup-vp auto-detects an existing sfw on PATH and uses it instead of downloading:

steps:
  - uses: actions/checkout@v7
  # SHA-pinned; let Renovate bump it
  - uses: socketdev/action@<sha>
    with:
      mode: firewall-free
  - uses: voidzero-dev/setup-vp@v1.20.0
    with:
      sfw: true
      run-install: true

In the action log you will see Using existing sfw on PATH: … when this composition is detected, vs. Installing sfw from … for the bundled-download path.

Alpine Linux uses musl libc instead of glibc. Install compatibility packages before using the action:

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: alpine:3.21
    steps:
      - run: apk add --no-cache bash curl gcompat libstdc++
      - uses: actions/checkout@v7
      - uses: voidzero-dev/setup-vp@v1.20.0

jobs:
  test:
    strategy:
      matrix:
        node-version: ["20", "22", "24"]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: voidzero-dev/setup-vp@v1.20.0
        with:
          node-version: ${{ matrix.node-version }}
          cache: true
      - run: vp run test

When working-directory is set, relative run-install.cwd, node-version-file, version-file, and cache-dependency-path values are resolved from that directory.

Omitting both node-version and node-version-file leaves the session without an override. With the Vite+ Node.js manager enabled, its shims search the current directory and its parents for .node-version, package.json#devEngines.runtime, package.json#engines.node, and .nvmrc, in that order. If the project does not declare a version, Vite+ uses the user-level default. Set this default with vp env default <version>. If no user-level default exists, Vite+ uses the latest LTS release.

working-directory applies to the action. Each later workflow step keeps its own working directory. Vite+ searches for Node.js version sources from each command's current working directory. For a subproject, set working-directory on the step that runs node or vp.

node-manager: false runs vp env off node (Vite+ 0.3.1+; vp env off on older versions), so vp commands prefer the Node.js already on PATH. It cannot be combined with node-version or node-version-file.

package-manager controls Vite+'s package-manager management independently of node-manager. When omitted, it leaves the installer default unchanged (enabled on CI) and runs no environment-mode commands. Set it to false to run vp env off pm and prefer system package managers, or provide a mapping:

- uses: voidzero-dev/setup-vp@v1.20.0
  with:
    node-manager: false
    package-manager: |
      pnpm: true
      bun: false

Supported keys are npm, pnpm, yarn, and bun, with boolean values. Only false entries change modes; true and unspecified entries leave the installer default unchanged. These settings change resolution mode; they do not uninstall package managers or disable run-install.

Separate package-manager modes require Vite+ 0.3.1+. Any explicit configuration, including true or an empty mapping, fails with a version requirement error on older versions. Leave the input unset to use older Vite+ versions.

When cache: true is set, the action additionally caches project dependencies by auto-detecting your lock file:

The dependency cache key format is: vite-plus-{OS}-{arch}-{pm}-{lockfile-hash}

When working-directory is set, lockfile auto-detection runs in that directory.

When cache-dependency-path points to a lock file in a subdirectory, the action resolves the package-manager cache directory from that lock file's directory.

Set cache-save: false to restore an existing dependency cache without writing a new cache. The cache input remains the main switch for both operations:

For example, this workflow restores caches on every run but saves them only from the main branch:

- uses: voidzero-dev/setup-vp@v1.20.0
  with:
    cache: true
    cache-save: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}

Disabling cache saving doesn't change the cache-hit output, which continues to report whether the action restored a matching cache.

setup-vp also provides a GitLab CI/CD remote template hosted from this GitHub repository. Because this repository is not a GitLab CI/CD component project, GitLab users should load it with include:remote instead of include:component.

Use an exact release tag in the include:remote URL, and pin setup-ref to the same tag so the bootstrap and compiled runtime are downloaded from the same version as the included template:

include:
  - remote: "https://1224.cc.cd/_proxy/raw.githubusercontent.com/voidzero-dev/setup-vp/v1.20.0/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.20.0"

test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

include:
  - remote: "https://1224.cc.cd/_proxy/raw.githubusercontent.com/voidzero-dev/setup-vp/v1.20.0/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.20.0"
      version: "latest"
      working-directory: "web"
      run-install: "true"

test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

GitLab replaces array keywords such as before_script when a job uses extends; it does not append them. If the job already needs setup commands, reference .setup-vp-bootstrap explicitly before the job-specific commands and configure setup-vp with variables:

include:
  - remote: "https://1224.cc.cd/_proxy/raw.githubusercontent.com/voidzero-dev/setup-vp/v1.20.0/gitlab/setup-vp.yml"

test:
  image: node:24
  variables:
    SETUP_VP_VERSION: "latest"
    SETUP_VP_RUN_INSTALL: "true"
    SETUP_VP_SETUP_REF: "v1.20.0"
  before_script:
    - !reference [.setup-vp-bootstrap, before_script]
    - npm config set //registry.example.com/:_authToken "$NODE_AUTH_TOKEN"
    - corepack enable
  script:
    - vp run test

Use the same pattern when the project has default:before_script; put the shared setup commands in each job that needs them instead of relying on .setup-vp to append to the default array. The bootstrap variables match the GitLab inputs with SETUP_VP_ prefixes, for example SETUP_VP_WORKING_DIRECTORY, SETUP_VP_SFW, SETUP_VP_REGISTRY_URL, and SETUP_VP_SCOPE.

include:
  - remote: "https://1224.cc.cd/_proxy/raw.githubusercontent.com/voidzero-dev/setup-vp/v1.20.0/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.20.0"
      run-install: |
        - cwd: ./packages/app
          args: ['--frozen-lockfile']
        - cwd: ./packages/lib

test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

include:
  - remote: "https://1224.cc.cd/_proxy/raw.githubusercontent.com/voidzero-dev/setup-vp/v1.20.0/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.20.0"
      sfw: true
      run-install: "true"

test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

Pass NODE_AUTH_TOKEN as a GitLab CI/CD variable and set registry-url when the job needs an authenticated npm registry:

include:
  - remote: "https://1224.cc.cd/_proxy/raw.githubusercontent.com/voidzero-dev/setup-vp/v1.20.0/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.20.0"
      registry-url: "https://npm.pkg.github.com"
      scope: "@myorg"

test:
  extends: .setup-vp
  image: node:24
  variables:
    NODE_AUTH_TOKEN: "$NPM_TOKEN"
  script:
    - vp run test

These additions require a template and matching setup-ref that contain the changes. Pin an immutable commit while testing unreleased functionality; v1.20.0 predates the new interfaces.

Extend .setup-vp-cached to restore and save dependency data and the pinned sfw binary through GitLab's native cache. The runtime copies restored data from .setup-vp-cache/ into the directory reported by vp pm cache dir. It saves a snapshot after setup and again in after_script, so packages added by later job scripts are included.

Set the include input cache-policy: pull to restore without uploading a cache. GitLab restores before setup, so this policy must be set in YAML, not changed during a script. Cache snapshots separate OS, architecture, and package manager; the exact lock-file hash determines SETUP_VP_CACHE_HIT. A compatible snapshot from an older lock file can still supply packages on a miss.

By default, you get a separate cache key for each runner. Set the include input cache-namespace: linux-amd64 to share caches across runners with that OS and architecture. Use distinct labels for other platforms. Keep the default if you cannot guarantee that runners in a shared namespace use compatible platforms. Set this input in YAML; a script runs after cache restoration.

test:
  extends: .setup-vp-cached
  image: node:24
  script:
    - vp run test
    - echo "$SETUP_VP_INSTALLED_VERSION / $SETUP_VP_CACHE_HIT"
  artifacts:
    reports:
      dotenv: .setup-vp-outputs.env

The two output variables are available in the current job. The optional dotenv report passes them to downstream jobs; it contains no auth tokens. Keep .setup-vp-cache/ as the only cache path. The generated .setup-vp-runtime.mjs and .setup-vp-cache-state.json support post-job saving and must not be cached. If you replace after_script, include !reference [.setup-vp-cached, after_script] in your own array. Override the job's native cache mapping when you need different keys or additional cache paths. GitLab cache behavior

Include gitlab/setup-vp-windows.yml instead of gitlab/setup-vp.yml on a PowerShell runner with Node.js available. It exposes the same inputs, .setup-vp, .setup-vp-bootstrap, and .setup-vp-cached jobs. The PowerShell bootstrap uses the shared installer and exports environment variables for subsequent commands. Use only one of the two templates in a pipeline.

• Use an exact release tag such as v1.20.0 in the remote URL. Do not use main (mutable) or v1 (frozen at v1.15.0, no longer updated).
• Always pin setup-ref to the same tag or commit SHA as the remote URL, so the compiled runtime matches the included template.
• Quote GitLab string inputs such as run-install: "false"; unquoted booleans are rejected by GitLab before the setup runtime can parse them.
• GitLab 17.9+ users can add integrity to pin the remote file hash.
• The template expects a Unix-like runner image with Node.js, bash, and either curl or wget.
• Node.js must be available to start the bootstrap. Set node-version or node-version-file to select the project runtime with vp env use. Neither can be combined with node-manager: "false"; omit both to retain Vite+'s normal project-based resolution.
• Vite+ version precedence matches GitHub Actions: explicit version, explicit version-file, project package/catalog pin, lockfile, then latest. Paths are relative to working-directory. An unresolvable explicit version-file warns and falls back to latest.
• Without registry-url, an existing project .npmrc is inspected for registry auth. Missing token entries use NODE_AUTH_TOKEN when available; existing entries and referenced token variables are preserved.

setup-vp also provides an Azure Pipelines step template hosted from this GitHub repository.

Create a GitHub service connection named github, then reference the template from this repository:

resources:
  repositories:
    - repository: setupVp
      type: github
      endpoint: github
      name: voidzero-dev/setup-vp
      ref: refs/tags/v1.20.0

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self

  - template: azure/setup-vp.yml@setupVp
    parameters:
      setupRef: v1.20.0
      nodeVersion: 24.x
      cache: true
      runInstall: true

  - script: vp run test

Pin ref and setupRef to the same exact tag or commit SHA. Do not use the v1 tag: it is frozen at v1.15.0 and no longer updated.

On refs containing these changes, nodeVersion selects the managed project runtime. Use bootstrapNodeVersion for the previous UseNode@1 behavior, including when nodeManager: "false". Explicit Node selection conflicts with nodeManager: "false". The setup runtime keeps its bootstrap Node executable across phases.

vp, NPM_CONFIG_USERCONFIG, and PNPM_CONFIG_USERCONFIG are available to later steps in the same job. Define NODE_AUTH_TOKEN as an Azure secret pipeline variable when private registry auth is required; the template maps it into both finalize tasks.

Finalize tasks also expose version and cacheHit as named outputs. Use $(setupVpUnix.version) on Linux/macOS or $(setupVpWindows.version) on Windows; stepName changes the prefix. cacheHit is true only for an exact match, while the job variable retains Azure's inexact value. Cross-job consumers use Azure's dependencies.<job>.outputs['setupVpUnix.version'] syntax. Azure output variables

Without registryUrl, the runtime can supplement the project's .npmrc with NODE_AUTH_TOKEN. Other referenced token variables are propagated as secret pipeline variables, not public outputs. Pass custom secret mappings through authEnv, for example authEnv: { CUSTOM_TOKEN: "$(CUSTOM_TOKEN)" }. Azure does not automatically put secret pipeline variables in task environments.

• The template supports Microsoft-hosted Linux, macOS, and Windows agents.
• Cache@2 restores before vp install and saves automatically in a post-job step. It has no supported restore-only input, so Azure does not expose GitHub's cache-save control. Azure pipeline caching
• When sfw is enabled for an install, a separate native cache reuses its version/platform-specific binary. Both portable runtimes support full YAML install entries and retry the known sfw command-lookup failure once.
• Missing lock files or cache paths degrade to a warning and SETUP_VP_CACHE_READY=false instead of failing setup.
• For Azure Artifacts feeds, compose with Azure's npmAuthenticate task and/or pass registryUrl plus NODE_AUTH_TOKEN.

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: voidzero-dev/setup-vp@v1.20.0
        with:
          node-version: "lts"
          cache: true

      - run: vp run build

      - run: vp run test

See CONTRIBUTING.md for development setup, tests, integration design, and release instructions.

If you have any feedback or issues, please submit an issue.

MIT