setup-vp

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

Features

• 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

Versioning

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

- uses: voidzero-dev/[email protected]

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

[!WARNING]

The moving major tag v1 is frozen at v1.15.0 and no longer updated. Workflows that use voidzero-dev/setup-vp@v1 keep working but stay on v1.15.0 and will not receive new releases: switch them to an exact version tag. The same applies to the GitLab and Azure templates; use an exact tag in the include:remote URL / repository ref and in setup-ref / setupRef.

Usage

Basic Usage

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/[email protected]

With Node.js Version

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/[email protected]
    with:
      node-version: "lts"

With Node.js Version File

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/[email protected]
    with:
      node-version-file: ".node-version"

Keep the Runner's Node.js

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/[email protected]
    with:
      node-manager: false

With Working Directory

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/[email protected]
    with:
      working-directory: web
      node-version-file: ".nvmrc"
      cache: true
      run-install: true

With Caching and Install

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/[email protected]
    with:
      node-version: "lts"
      cache: true
      run-install: true

Specific Version

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/[email protected]
    with:
      version: "1.2.3"
      node-version: "lts"
      cache: true

Use Package Managers Directly

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/[email protected]
  - run: pnpm --version

Version from package.json / Catalog

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/[email protected]
    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/[email protected]
    with:
      version-file: package.json
      cache: true

When the package.json entry is catalog: / catalog:, 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.)

Advanced Run Install

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

With Private Registry (GitHub Packages)

Set registry-url explicitly and pass NODE_AUTH_TOKEN via env to configure authentication for that registry:

steps:
  - uses: actions/checkout@v7
  - uses: voidzero-dev/[email protected]
    with:
      node-version: "lts"
      registry-url: "https://npm.pkg.github.com"
      scope: "@myorg"
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Without registry-url, the action respects existing auth entries in the project .npmrc and propagates their referenced environment variables. It does not create token entries from registry URLs in repository files, even when NODE_AUTH_TOKEN is set. Jobs that relied on automatic token entries must set registry-url or supply an explicit auth entry:

@myorg:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

An explicit registry-url bypasses project .npmrc auth propagation in the action. The package manager still reads the project .npmrc according to its own configuration rules.

With Socket Firewall Free (sfw)

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/[email protected]
    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.

For Vite+ preview builds (0.0.0-commit.<40-character SHA>), setup-vp automatically disables sfw, even when it is enabled, and logs a warning. Dependency installation runs with plain vp install. This applies to GitHub Actions, GitLab CI/CD, and Azure Pipelines, including when sfw is already on PATH.

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

Advanced: stricter supply chain via socketdev/action

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/[email protected]
    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.

[!NOTE]

macOS / Windows require Vite+ v0.1.23 or newer. Earlier vp releases didn't honor HTTPS_PROXY / SSL_CERT_FILE, so sfw vp install failed the TLS handshake on macOS / Windows (it always worked on Linux). The action's default version: latest satisfies this; if you pin an older vp and enable sfw on macOS / Windows, the install will fail the handshake. On a runner architecture with no published sfw binary (e.g. riscv64), the action logs a warning and falls back to plain vp install.

Alpine Container

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/[email protected]

Matrix Testing with Multiple Node.js Versions

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

Inputs

| Input | Description | Required | Default | | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | --------------------- | | version | Version of Vite+ to install. Takes precedence over version-file | No | auto / latest | | version-file | Path to a file to resolve the Vite+ version from (package.json, pnpm-workspace.yaml, or .yarnrc.yml) | No | | | node-version | Node.js version to install via vp env use | No | Vite+ resolution | | node-version-file | Path to file containing Node.js version (.nvmrc, .node-version, .tool-versions, package.json) | No | | | node-manager | Control Vite+'s Node.js manager: false keeps the runner's Node.js, true leaves the installer default unchanged | No | Auto (on for CI) | | package-manager | Opt out of management for all package managers or individual npm, pnpm, yarn, and bun families (Vite+ 0.3.1+) | No | Unset (enabled on CI) | | working-directory | Project directory used for relative paths, lockfile auto-detection, environment checks, and default install | No | Workspace root | | run-install | Run vp install after setup. Accepts boolean or YAML object with cwd/args | No | true | | sfw | Wrap vp install with Socket Firewall Free (sfw) | No | false | | cache | Enable caching of project dependencies | No | false | | cache-save | Save the dependency cache in the post action. Has no effect when cache is false | No | true | | cache-dependency-path | Path to lock file for cache key generation | No | Auto-detected | | registry-url | Optional registry to set up for auth. Sets the registry in .npmrc and reads auth from NODE_AUTH_TOKEN | No | | | scope | Optional scope for scoped registries. Falls back to repo owner for GitHub Packages | No | |

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 . 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/[email protected]
  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.

Outputs

| Output | Description | | ----------- | ---------------------------------------- | | version | The installed version of Vite+ | | cache-hit | Boolean indicating if cache was restored |

Caching

Reuse an installed version

On runners that retain the Vite+ installation, the GitHub Action reuses an active exact version when its files and shims pass the reuse checks and Node.js and package-manager management are enabled. This applies to versions that support VP_DUMP_DIRS (0.3.0 and later). The action still applies requested management opt-outs, sets up Node.js, and runs the remaining steps.

The action runs the installer when it needs to change versions or repair the installation. It also runs the installer for dist-tags such as latest, version ranges, preview builds, and older releases. Reuse works with cache: false and does not restore an installation onto a fresh runner.

Dependency Cache

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

| Lock File | Package Manager | Cache Directory | | ------------------- | --------------- | --------------- | | pnpm-lock.yaml | pnpm | pnpm store | | bun.lockb | bun | bun cache | | bun.lock | bun | bun cache | | package-lock.json | npm | npm cache | | yarn.lock | yarn | yarn cache |

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.

Control cache saving

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:

| cache | cache-save | Restore | Save | | ------- | ----------------- | ------- | ---- | | false | Any value | No | No | | true | Omitted or true | Yes | Yes | | true | false | Yes | No |

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

- uses: voidzero-dev/[email protected]
  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.

GitLab CI/CD

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.

Basic GitLab Usage

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://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.21.2/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.21.2"
test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

With GitLab Inputs

String inputs are passed as literal environment values. Quotes, dollar signs, and multiline values do not become shell commands. Inputs take precedence over the corresponding SETUP_VP_* variables when you extend .setup-vp or .setup-vp-cached; use .setup-vp-bootstrap directly to configure setup through variables instead.

setup-ref accepts ASCII letters, digits, underscores, and hyphens, with single dots or slashes between these groups (for example, v1.21.2 or refs/tags/v1.21.2). The templates and bootstrap scripts reject other values before downloading executable files. The same validation applies to SETUP_VP_SETUP_REF when using .setup-vp-bootstrap directly. Keep this value under maintainer control because it selects code that runs on the runner.

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.21.2/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.21.2"
      version: "latest"
      working-directory: "web"
      run-install: "true"
test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

With Existing GitLab before_script

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://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.21.2/gitlab/setup-vp.yml"
test:
  image: node:24
  variables:
    SETUP_VP_VERSION: "latest"
    SETUP_VP_RUN_INSTALL: "true"
    SETUP_VP_SETUP_REF: "v1.21.2"
  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.

Advanced GitLab Run Install

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.21.2/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.21.2"
      run-install: |
        - cwd: ./packages/app
          args: ['--frozen-lockfile']
        - cwd: ./packages/lib
test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

With GitLab Socket Firewall Free (sfw)

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.21.2/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.21.2"
      sfw: true
      run-install: "true"
test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

With Private Registry

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://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.21.2/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.21.2"
      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

GitLab Inputs

| Input | Description | Default | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | version | Explicit Vite+ version or dist-tag; empty auto-detects from the project | Auto-detected | | version-file | Read Vite+ from package.json, pnpm-workspace.yaml, or .yarnrc.yml | | | node-version | Node.js version selected with vp env use | | | node-version-file | Read Node.js from .nvmrc, .node-version, .tool-versions, or package.json | | | cache-dependency-path | Lock file relative to working-directory; otherwise auto-detect | | | cache-policy | Native policy for .setup-vp-cached: pull-push or restore-only pull | pull-push | | cache-namespace | Cache partition; set an OS/architecture label to share across compatible runners | $CI_RUNNER_ID | | working-directory | Project directory used for relative paths and default vp install execution | . | | run-install | String input for vp install after setup. Use "true"/"false" or a YAML object/list with cwd/args | true | | sfw | Wrap vp install with Socket Firewall Free | false | | node-manager | String input: "false" keeps the runner image's Node.js (disables Node.js management after installation); "true" leaves the installer default unchanged; empty lets the installer decide (enabled on CI) | | | package-manager | String input: "true", "false", or a YAML mapping of npm, pnpm, yarn, and bun to booleans (Vite+ 0.3.1+) | Unset (enabled on CI) | | registry-url | Optional registry URL to write to a temporary .npmrc | | | scope | Optional scope for authenticating against scoped registries | | | setup-ref | setup-vp ref used to download the GitLab bootstrap and compiled runtime. Always set it to the same tag as the remote URL; the default is the latest release when the template was published | v1.21.2 |

GitLab Caching and Outputs

GitLab caching and outputs require v1.21.0 or newer. Use the same version for the remote template and setup-ref.

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

GitLab Windows Runners

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.

GitLab Notes

• Use an exact release tag such as v1.21.2 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, existing project .npmrc auth entries and referenced token variables are preserved. Registry URLs in repository files do not receive automatic token entries. Set registry-url to generate auth configuration for a registry.

Azure Pipelines

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

Basic Azure Usage

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.21.2
pool:
  vmImage: ubuntu-latest
steps:
  - checkout: self
- template: azure/setup-vp.yml@setupVp
    parameters:
      setupRef: v1.21.2
      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.

setupRef accepts ASCII letters, digits, underscores, and hyphens, with single dots or slashes between these groups (for example, v1.21.2 or refs/tags/v1.21.2). Other values fail before any bootstrap download. Keep this parameter under maintainer control because it selects code that runs on the agent.

Azure Parameters

| Parameter | Default | Description | | ---------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | version | Auto-detected | Explicit Vite+ version/dist-tag; empty uses the same resolution rules as GitHub and GitLab. | | versionFile | | Vite+ version file relative to workingDirectory. | | nodeVersionFile | | Node.js version file relative to workingDirectory. | | bootstrapNodeVersion | 24.x | Passed to UseNode@1 to start the setup runtime; empty uses the agent's existing Node.js. | | stepName | setupVp | Prefix for named finalize tasks and their output variables. Use a unique prefix for each template invocation. | | workingDirectory | . | Project directory for lock detection and default vp install. | | runInstall | true | Run vp install; accepts boolean or object/list with cwd and args. | | sfw | false | Wrap vp install with Socket Firewall Free. | | authEnv | {} | Extra environment mappings for custom registry secrets, such as { PRIVATE_TOKEN: "$(PRIVATE_TOKEN)" }. | | registryUrl | | Optional registry URL for a temporary .npmrc. | | scope | | Optional npm registry scope. | | setupRef | v1.21.2 | Ref used to download bootstrap scripts and dist/azure/index.mjs. Always set it to the same tag as ref; the default is the latest release when the template was published. | | nodeVersion | | Select Node.js with vp env use; takes precedence over nodeVersionFile. | | nodeManager | | Control Vite+'s Node.js manager: false keeps the agent's Node.js (e.g. from UseNode@1); true leaves the installer default unchanged; empty lets the installer decide. | | packageManager | Unset (enabled on CI) | Boolean or object mapping npm, pnpm, yarn, and bun to booleans (Vite+ 0.3.1+). Only false entries change modes. | | cache | false | Enable Azure Cache@2 around the package-manager cache directory. | | cacheDependencyPath | | Explicit lock file relative to workingDirectory; otherwise auto-detect. |

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.

Azure Job Variables

| Variable | Purpose | | ---------------------------- | --------------------------------------------------------------------- | | SETUP_VP_INSTALLED_VERSION | Installed global Vite+ version (unknown when parsing fails). | | SETUP_VP_CACHE_HIT | true, inexact, or false from Cache@2 when caching is enabled. |

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..outputs['setupVpUnix.version'] syntax. Azure output variables

Without registryUrl, the runtime preserves existing project .npmrc auth entries but does not generate token entries for its registry URLs. Set registryUrl to generate auth configuration for a registry. Referenced custom 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.

Azure Notes

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

Example Workflow

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
- uses: voidzero-dev/[email protected]
        with:
          node-version: "lts"
          cache: true
- run: vp run build
- run: vp run test

Contributing

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

Feedback

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

License

MIT