Docker

Vite+ publishes an official Docker image with the vp CLI preinstalled:

ghcr.io/voidzero-dev/vite-plus

Use it for builds, CI, and devcontainers. It is not intended as a production runtime image.

vp resolves the Node.js version from your project (.node-version, devEngines.runtime, or engines.node) and downloads that exact version during install/build. This means the image does not need Node-version-specific tags.

For production, use a multi-stage build: build the app with the Vite+ image, then copy only the resolved Node.js binary, build output, and production dependencies into a smaller runtime image.

Image tags

Tags track the vp version:

Tag	Meaning
ghcr.io/voidzero-dev/vite-plus:latest	Latest release
ghcr.io/voidzero-dev/vite-plus:<major>	Latest major
ghcr.io/voidzero-dev/vite-plus:<major>.<minor>	Latest minor
ghcr.io/voidzero-dev/vite-plus:<major>.<minor>.<patch>	Exact 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 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.

Production: SSR / Node.js server app

For apps that run Node.js in production (SvelteKit, Nuxt, a custom Vite SSR server, and so on), build with the toolchain image and copy the resolved Node.js and the built app into a slim runtime stage:

Dockerfile

# syntax=docker/dockerfile:1

# --- build stage: the official Vite+ toolchain image ---
FROM ghcr.io/voidzero-dev/vite-plus:latest AS build
WORKDIR /app

# Install dependencies first so this layer is cached across source changes.
COPY --chown=vp:vp package.json pnpm-lock.yaml pnpm-workspace.yaml .node-version* ./
RUN vp install --frozen-lockfile

# Build. vp reads .node-version and provisions that exact Node.js automatically.
COPY --chown=vp:vp . .
RUN vp build

# Export the exact resolved Node.js binary for the runtime stage.
RUN cp "$(vp env which node | head -1)" /tmp/node

# --- deps stage: production-only dependencies ---
# A separate, fresh `--prod` install so devDependencies (including the vite-plus
# toolchain) are excluded. Running `--prod` over the full install above would not
# prune the already-installed devDependencies.
FROM ghcr.io/voidzero-dev/vite-plus:latest AS deps
WORKDIR /app
COPY --chown=vp:vp package.json pnpm-lock.yaml pnpm-workspace.yaml .node-version* ./
RUN vp install --frozen-lockfile --prod

# --- runtime stage: small, glibc, no vp ---
FROM debian:bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production

# The exact Node.js from .node-version (official, signature-verified build).
COPY --from=build /tmp/node /usr/local/bin/node

COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/package.json ./

USER nobody
EXPOSE 3000
CMD ["node", "dist/server.js"]

The deployed image contains only Node.js plus your app and production dependencies, and matches .node-version exactly. It is much smaller than the default node:* image; see the distroless tip below for the smallest result.

Prune production dependencies in a separate stage

Install production dependencies in their own deps stage as shown. Running vp install --prod after a full vp install in the same stage does not remove the already-installed devDependencies, so the vite-plus toolchain would be copied into the runtime image. If your server bundle is fully self-contained (no un-bundled runtime dependencies), you can skip copying node_modules entirely.

Smaller still

For a shell-less, minimal-CVE runtime, swap the runtime base for distroless (gcr.io/distroless/cc) and keep an ENTRYPOINT in vector form. It is glibc based, so the copied Node.js binary remains compatible.

Production: static SPA / SSG

A static site needs no Node.js at runtime; serve the build output with any static server:

Dockerfile

FROM ghcr.io/voidzero-dev/vite-plus:latest AS build
WORKDIR /app
COPY --chown=vp:vp package.json pnpm-lock.yaml pnpm-workspace.yaml .node-version* ./
RUN vp install --frozen-lockfile
COPY --chown=vp:vp . .
RUN vp build

FROM nginx:alpine AS runtime
COPY --from=build /app/dist /usr/share/nginx/html

Continuous integration

Use the image directly in container-based CI (GitLab CI, Buildkite, CircleCI, Jenkins, and others):

.gitlab-ci.yml

build:
  image: ghcr.io/voidzero-dev/vite-plus:latest
  script:
    - vp install --frozen-lockfile
    - vp check
    - vp test
    - vp build

On GitHub Actions, prefer setup-vp 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:

.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

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.

Devcontainers

Use the image as a ready-to-go development container with the toolchain preinstalled:

.devcontainer/devcontainer.json

{
  "image": "ghcr.io/voidzero-dev/vite-plus:latest",
}

Ad-hoc usage

Run any vp command against a project without installing vp on your machine:

docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp build

Notes

• Node.js version: provisioned from .node-version, engines.node, or devEngines.runtime at build time, so there is no Node.js-specific image tag. The dependency COPY uses a .node-version* glob so the file is optional: projects that pin via engines.node/devEngines.runtime need no .node-version, and 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). 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.
• glibc: the image is glibc based so it uses the official, signature-verified Node.js builds.
• Custom base image: to add vp to your own base image instead, run the installer: curl -fsSL https://vite.plus | bash (set VP_VERSION to pin a version).