### Migrating Existing Workflows to setup-vp

Source: https://viteplus.dev/guide/ci

This example shows how to simplify an existing GitHub Actions workflow by replacing multiple Node.js and package manager setup steps with a single `setup-vp` action.

```yaml
- uses: pnpm/action-setup@v6
  with:
    version: 11

- uses: actions/setup-node@v6
  with:
    node-version: '24'
    cache: pnpm

- run: pnpm ci && pnpm dev:setup
- run: pnpm check
- run: pnpm test
```

```yaml
- uses: voidzero-dev/setup-vp@v1
  with:
    node-version: '24'
    cache: true

- run: vp install && vp run dev:setup
- run: vp check
- run: vp test
```

--------------------------------

### Vite+ Quick Start Commands

Source: https://viteplus.dev/guide

Use these commands to quickly create, install dependencies, develop, check, test, and build your Vite+ project.

```bash
vp create # Create a new project
vp install # Install dependencies
vp dev # Start the dev server
vp check # Format, lint, type-check
vp test # Run JavaScript tests
vp build # Build for production
```

--------------------------------

### Install Global `vp` Preview (Bash)

Source: https://viteplus.dev/guide/upgrade

Install a preview build of the global Vite+ CLI by passing a pull request number or commit SHA to the installer script. This command fetches the specified preview build through the registry bridge.

```bash
curl -fsSL https://vite.plus | VP_PR_VERSION=<pr-or-sha> bash
```

--------------------------------

### Install Global `vp` Preview (PowerShell)

Source: https://viteplus.dev/guide/upgrade

Install a preview build of the global Vite+ CLI on Windows using PowerShell. Set the VP_PR_VERSION environment variable with a pull request number or commit SHA before running the installer script.

```powershell
$env:VP_PR_VERSION = "<pr-or-sha>"
irm https://vite.plus/ps1 | iex
Remove-Item Env:\VP_PR_VERSION
```

--------------------------------

### GitHub Actions CI Setup with setup-vp

Source: https://viteplus.dev/guide/ci

Use this snippet to set up Vite+ in your GitHub Actions workflow. It installs the specified Node.js version, enables dependency caching, and runs standard Vite+ commands.

```yaml
- uses: voidzero-dev/setup-vp@v1
  with:
    node-version: '24'
    cache: true
- run: vp install
- run: vp check
- run: vp test
- run: vp build
```

--------------------------------

### Install and Configure Commit Hooks

Source: https://viteplus.dev/guide/commit-hooks

Use `vp config` to set up project hooks and related integrations. Use `--hooks-dir` to specify a custom directory for hooks. Use `--no-hooks` to leave existing Git hook setup unchanged. Use `--no-agent` to skip updates to coding agent instruction files.

```bash
vp config
vp config --hooks-dir .vite-hooks
vp config --no-hooks
vp config --no-agent
```

--------------------------------

### Vite+ Installation for Workspace

Source: https://viteplus.dev/guide/install

An alternative shorthand for filtering installation to a specific workspace.

```bash
vp install -w
```

--------------------------------

### vpx Examples

Source: https://viteplus.dev/guide/vpx

Demonstrates various ways to use `vpx` to run different tools and packages with arguments.

```bash
vpx eslint .
```

```bash
vpx create-vue my-app
```

```bash
vpx typescript@5.5.4 tsc --version
```

```bash
vpx -p cowsay -c 'echo "hi" | cowsay'
```

--------------------------------

### vp exec Examples

Source: https://viteplus.dev/guide/vpx

Shows how to run project-local binaries like `eslint` and `tsc` using `vp exec`.

```bash
vp exec eslint .
```

```bash
vp exec tsc --noEmit
```

--------------------------------

### Basic Vite+ Installation

Source: https://viteplus.dev/guide/install

Run this command to install project dependencies using Vite+'s underlying package manager.

```bash
vp install
```

--------------------------------

### vp dlx Examples

Source: https://viteplus.dev/guide/vpx

Illustrates using `vp dlx` to run package binaries like `create-vite` and `typescript` without adding them to dependencies.

```bash
vp dlx create-vite
```

```bash
vp dlx typescript tsc --version
```

--------------------------------

### Verify Vite+ Installation

Source: https://viteplus.dev/guide

After installation, run this command in a new shell to verify that Vite+ is installed correctly and to view its help information.

```bash
vp help
```

--------------------------------

### Start Vite Development Server

Source: https://viteplus.dev/guide/dev

Use this command to launch the Vite development server. It provides the standard Vite development experience.

```bash
vp dev
```

--------------------------------

### Global Package Installation with Vite+

Source: https://viteplus.dev/guide/install

Installs a package globally using Vite+'s custom global package management system, which is separate from the Node.js global installation.

```bash
vp install -g <pkg>
```

--------------------------------

### Vite+ Create Command Examples

Source: https://viteplus.dev/guide/create

Demonstrates various ways to use the 'vp create' command, including interactive mode, scaffolding different project types, using shorthand and full package names for templates, and utilizing remote templates from GitHub or URLs.

```bash
# Interactive mode
vp create
```

```bash
# Create a Vite+ monorepo, application, library, or generator
vp create vite:monorepo
vp create vite:application
vp create vite:library
vp create vite:generator
```

```bash
# Use shorthand community templates
vp create vite
vp create @tanstack/start
vp create svelte
```

```bash
# Use full package names
vp create create-vite
vp create create-next-app
```

```bash
# Use remote templates
vp create github:user/repo
vp create https://github.com/user/template-repo
```

--------------------------------

### Install Vite+ on Windows

Source: https://viteplus.dev/guide

Use this PowerShell command to download and execute the Vite+ installation script on Windows systems.

```powershell
irm https://vite.plus/ps1 | iex
```

--------------------------------

### Install Project Dependencies

Source: https://viteplus.dev/guide/install

Installs dependencies based on the current package.json and lockfile. Use --frozen-lockfile to prevent lockfile changes.

```bash
vp install
```

```bash
vp install --frozen-lockfile
```

```bash
vp install --no-frozen-lockfile
```

```bash
vp install --lockfile-only
```

```bash
vp install --prefer-offline
```

```bash
vp install --offline
```

```bash
vp install --ignore-scripts
```

```bash
vp install --filter <pattern>
```

```bash
vp install -w
```

--------------------------------

### Vite+ Environment Setup Commands

Source: https://viteplus.dev/guide/env

Commands to set up and configure the Vite+ environment for Node.js management.

```bash
# Setup
vp env setup                  # Create shims for node, npm, npx, corepack
vp env on                     # Use Vite+ managed Node.js
vp env print                  # Print shell snippet for this session
```

```bash
# Manage
vp env pin lts                # Pin the project to the latest LTS release
vp env install                # Install the version from .node-version or package.json
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
```

```bash
# 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-remote --lts      # List only LTS versions
```

```bash
# Execute
vp env exec --node lts npm i  # Execute npm with latest LTS
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
```

--------------------------------

### Install Vite+ on macOS/Linux

Source: https://viteplus.dev/guide

Use this command to download and execute the Vite+ installation script on macOS and Linux systems.

```bash
curl -fsSL https://vite.plus | bash
```

--------------------------------

### Inspect Dependencies

Source: https://viteplus.dev/guide/install

Provides information about installed packages, their reasons for being present, and registry metadata.

```bash
vp list
```

```bash
vp why react
```

```bash
vp info react
```

--------------------------------

### Install Node.js from Custom Mirror

Source: https://viteplus.dev/guide/env

Use this command to install a specific Node.js version from a custom mirror. Ensure the VP_NODE_DIST_MIRROR environment variable is set to your mirror's URL.

```bash
VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist vp env install 22
```

--------------------------------

### Package.json Scripts for Cache Sharing

Source: https://viteplus.dev/guide/cache

Example package.json scripts demonstrating how common tasks can share cache entries if caching is enabled.

```json
{
  "scripts": {
    "check": "vp lint && vp build",
    "release": "vp lint && deploy-script"
  }
}
```

--------------------------------

### Vite+ Installation with Lockfile Only

Source: https://viteplus.dev/guide/install

This command installs dependencies strictly based on the existing lockfile, without updating it.

```bash
vp install --lockfile-only
```

--------------------------------

### Vite+ Installation with Frozen Lockfile

Source: https://viteplus.dev/guide/install

Use this option to ensure that the lockfile is not modified during installation, guaranteeing reproducible builds.

```bash
vp install --frozen-lockfile
```

--------------------------------

### Full Migration with Local `vite-plus`

Source: https://viteplus.dev/guide/upgrade

To perform a full migration that includes first-time setup steps like git hooks and editor files, pass the `--full` flag to `vp migrate`.

```bash
vp migrate --full
```

--------------------------------

### Run Binary with vp dlx

Source: https://viteplus.dev/guide/vpx

Execute a package binary for one-off use without installing it as a project dependency. Ideal for temporary or infrequent tools.

```bash
vp dlx <package> [args...]
```

--------------------------------

### Example Cache Key Configuration

Source: https://viteplus.dev/guide/github-actions-cache

Configure a rolling primary key with a restore prefix for effective cache management. Include runner OS and architecture, and per-run identifiers like run_id and run_attempt. Track dependency files in the task fingerprint, not the Actions key.

```yaml
key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }}
restore-keys: |
  vite-task-${{ runner.os }}-${{ runner.arch }}-

```

--------------------------------

### Cache Miss Examples

Source: https://viteplus.dev/guide/cache

Examples of cache miss messages indicating why a task is being re-executed.

```bash
$ vp lint 
✗ cache miss: 'src/utils.ts' modified, executing
```

```bash
$ vp build 
✗ cache miss: env 'VITE_GREETING' changed, executing
```

```bash
$ vp test 
✗ cache miss: args changed, executing
```

--------------------------------

### Enable Managed Mode with vp env

Source: https://viteplus.dev/guide/env

Run this command to enable managed mode, ensuring shims always use the Vite+-managed Node.js installation.

```bash
vp env on
```

--------------------------------

### Vite+ Installation Filtered by Workspace

Source: https://viteplus.dev/guide/install

Install dependencies for a specific workspace within your project using the --filter flag.

```bash
vp install --filter web
```

--------------------------------

### Run Package Binary

Source: https://viteplus.dev/guide/install

Executes a package's binary without installing it as a project dependency.

```bash
vp dlx create-vite
```

--------------------------------

### Install libstdc++ on Alpine Linux

Source: https://viteplus.dev/guide

On Alpine Linux systems using musl, install the libstdc++ package before using Vite+ to ensure compatibility with the managed Node.js runtime.

```sh
apk add libstdc++
```

--------------------------------

### Upgrade Global `vp` Command

Source: https://viteplus.dev/guide/upgrade

Use these commands to manage the global `vp` binary. You can upgrade to the latest version, check for updates, install a specific version, or use a custom npm registry.

```bash
vp upgrade                        # upgrade to the latest version
vp upgrade --check                # check for updates without installing
vp upgrade <version>              # install a specific version
vp upgrade --registry <registry>  # use a custom npm registry
```

--------------------------------

### Ad-hoc Command Execution

Source: https://viteplus.dev/guide/docker

Run any `vp` command against your project without installing `vp` locally. This command mounts your current directory into the container and executes the specified `vp` command.

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

--------------------------------

### Vite+ Pack Configuration for Standalone Executables

Source: https://viteplus.dev/guide/pack

Configure `vp pack` to build standalone executables by setting the `entry` point and enabling the `exe` option. This is useful for shipping CLI tools that do not require a separate Node.js installation.

```typescript
import { defineConfig } from 'vite-plus';

export default defineConfig({
  pack: {
    entry: ['src/cli.ts'],
    exe: true,
  },
});
```

--------------------------------

### Composing Lint Configuration for Node.js

Source: https://viteplus.dev/guide/monorepo

Define reusable linting configurations for specific frameworks or environments. This example shows a Node.js-specific lint configuration.

```typescript
import type { OxlintOverride } from 'vite-plus/lint';

export const nodeLint = {
  env: {
    node: true,
  },
  rules: {
    'no-console': 'off',
  },
} satisfies Omit<OxlintOverride, 'files'>;
```

--------------------------------

### Vite+ Pack Configuration for Libraries

Source: https://viteplus.dev/guide/pack

Configure packaging options directly in the `pack` block of `vite.config.ts`. This example enables declaration file generation, specifies multiple output formats (ESM and CJS), and enables source maps.

```typescript
import { defineConfig } from 'vite-plus';

export default defineConfig({
  pack: {
    dts: true,
    format: ['esm', 'cjs'],
    sourcemap: true,
  },
});
```

--------------------------------

### CI Pipeline Configuration

Source: https://viteplus.dev/guide/docker

Integrate the Vite Plus Docker image into your CI pipeline to automate build and test processes. This example shows a basic GitLab CI configuration.

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

--------------------------------

### Build Static SPA/SSG with Dockerfile

Source: https://viteplus.dev/guide/docker

Use this Dockerfile to build a static Single Page Application (SPA) or Static Site Generator (SSG) project. It leverages a multi-stage build to first install dependencies and build the project, then copies the output to an Nginx server for serving.

```docker
FROM ghcr.io/voidzero-dev/vite-plus:latest AS build
WORKDIR /app
COPY --chown=vp:vp package.json pnpm-lock.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
```

--------------------------------

### List Available Templates

Source: https://viteplus.dev/guide/create

Run this command to display a list of all available built-in and popular shorthand templates that `vp create` recognizes.

```bash
vp create --list
```

--------------------------------

### Serve Production Build Locally

Source: https://viteplus.dev/guide/build

After building your application with `vp build`, use `vp preview` to serve the generated production build locally for testing.

```bash
vp build
vp preview
```

--------------------------------

### Basic `vp create` Usage

Source: https://viteplus.dev/guide/create

Use this command to interactively scaffold a new Vite+ project. It will prompt you for template selection and configuration.

```bash
vp create
```

--------------------------------

### Basic vp fmt Usage

Source: https://viteplus.dev/guide/fmt

Run `vp fmt` to format your project. Use `vp fmt --check` to check formatting without writing changes. Use `vp fmt . --write` to format the current directory and write changes.

```bash
vp fmt
```

```bash
vp fmt --check
```

```bash
vp fmt . --write
```

--------------------------------

### Create Project with Template Options

Source: https://viteplus.dev/guide/create

Pass options directly to the template using the `--` separator. This allows for fine-grained control over template-specific configurations.

```bash
vp create <template> -- <template-options>
```

--------------------------------

### Run Binary with vp exec

Source: https://viteplus.dev/guide/vpx

Execute a command specifically from the current project's `node_modules/.bin` directory. Useful for project-specific dependencies.

```bash
vp exec <command> [args...]
```

--------------------------------

### Basic Usage of vp pack

Source: https://viteplus.dev/guide/pack

Run `vp pack` to build libraries for production. Use `vp pack src/index.ts --dts` to generate declaration files. Enable watch mode with `vp pack --watch`.

```bash
vp pack
vp pack src/index.ts --dts
vp pack --watch
```

--------------------------------

### Global Package Management

Source: https://viteplus.dev/guide/install

Manages globally installed packages for tools available outside a single project. Use -g for global operations.

```bash
vp install -g typescript
```

```bash
vp uninstall -g typescript
```

```bash
vp update -g
```

```bash
vp list -g
```

```bash
vp outdated -g
```

--------------------------------

### VS Code Extensions Configuration

Source: https://viteplus.dev/guide/ide-integration

Installs the Vite Plus Extension Pack for VS Code, providing linting, formatting, and testing capabilities.

```json
{
  "recommendations": ["VoidZero.vite-plus-extension-pack"]
}
```

--------------------------------

### Pick from an Organization's Templates

Source: https://viteplus.dev/guide/create

Use `vp create @org` to open an interactive picker for templates published under an npm scope. You can also directly select a specific template or pin to a version.

```bash
# Open an interactive picker over @your-org/create's manifest
vp create @your-org

# Run a specific manifest entry directly
vp create @your-org:web

# Pin to an exact version or a dist-tag
vp create @your-org@1.2.3
vp create @your-org:web@next

# Set the org as the default for a repo (see create.defaultTemplate config)
vp create
```

--------------------------------

### Run Tests with Vite+

Source: https://viteplus.dev/guide/test

Execute tests using the `vp test` command. Use `vp test watch` to enter watch mode.

```bash
vp test
vp test watch
vp test run --coverage
```

--------------------------------

### Run Production Build

Source: https://viteplus.dev/guide/build

Execute the standard Vite+ production build. Use this command to generate optimized assets for deployment.

```bash
vp build
```

```bash
vp build --watch
```

```bash
vp build --sourcemap
```

--------------------------------

### Composing Lint Configuration for React

Source: https://viteplus.dev/guide/monorepo

Define reusable linting configurations for specific frameworks or environments. This example shows a React-specific lint configuration.

```typescript
import type { OxlintOverride } from 'vite-plus/lint';

export const reactLint = {
  plugins: ['typescript', 'react'],
  rules: {
    'react/self-closing-comp': 'error',
  },
} satisfies Omit<OxlintOverride, 'files'>;
```

--------------------------------

### Composing Root Lint Configuration with Imported Overrides

Source: https://viteplus.dev/guide/monorepo

Import and merge reusable lint configurations into the root vite.config.ts. This allows for modular and maintainable linting setups.

```typescript
import { defineConfig } from 'vite-plus';

import { nodeLint } from './tooling/lint/node';
import { reactLint } from './tooling/lint/react';

export default defineConfig({
  lint: {
    plugins: ['typescript'],
    options: {
      typeAware: true,
      typeCheck: true,
    },
    overrides: [
      {
        files: ['apps/web/**', 'packages/ui/**'],
        ...reactLint,
      },
      {
        files: ['apps/api/**'],
        ...nodeLint,
      },
    ],
  },
});
```

--------------------------------

### Running a Registered Generator with Vite+

Source: https://viteplus.dev/guide/create

Shows how to run a registered local template by its name or interactively. Options can be passed to the generator using '--'.

```bash
# Interactive mode lists registered local templates alongside the built-ins
vp create
```

```bash
# Run a registered template by its name
vp create component
```

```bash
# Pass options to the generator after --
vp create component -- --name @your-org/button
```

--------------------------------

### Restore Vite Task Cache in GitHub Actions

Source: https://viteplus.dev/guide/github-actions-cache

Restore the Vite Task cache after installing dependencies in your CI workflow. This ensures that cached build artifacts are available.

```yaml
name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: voidzero-dev/setup-vp@v1
        with:
          node-version: '24'
          cache: true

      - run: vp install

      - name: Restore Vite Task cache
        id: vite-task-cache
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.vite/task-cache
          key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }}
          restore-keys: |
            vite-task-${{ runner.os }}-${{ runner.arch }}-

      - run: vp run lint
      - run: vp run build

      - name: Save Vite Task cache
        if: success()
        uses: actions/cache/save@v6
        with:
          path: node_modules/.vite/task-cache
          key: ${{ steps.vite-task-cache.outputs.cache-primary-key }}
```

--------------------------------

### Execute a package.json Script

Source: https://viteplus.dev/guide/run

Use `vp run <script-name>` to execute a script defined in `package.json`. The output will be displayed directly.

```bash
vp run build
```

--------------------------------

### Devcontainer Configuration

Source: https://viteplus.dev/guide/docker

Configure your development environment using devcontainers. This JSON snippet specifies the Vite Plus Docker image to use, providing a pre-configured environment with the toolchain installed.

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

--------------------------------

### Running Package.json Scripts with Vite+

Source: https://viteplus.dev/guide

If you need to run a command defined in your project's `package.json` scripts, use `vp run` or `vpr`.

```bash
vp run <command>
vpr <command>
```

--------------------------------

### Package-Specific Scripts in Monorepo

Source: https://viteplus.dev/guide/monorepo

Define custom scripts for individual packages in their respective package.json files when commands differ per app. This example shows scripts for an API package.

```json
{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.json"
  }
}
```

--------------------------------

### Bypass Node.js Signature Verification

Source: https://viteplus.dev/guide/env

Temporarily bypass PGP signature verification for Node.js installations when facing keyring or certificate issues. The SHA-256 checksum is still verified, and a warning is issued.

```bash
VP_NODE_SKIP_SIGNATURE_VERIFY=1 vp env install 22
```

--------------------------------

### Run `vp migrate` command

Source: https://viteplus.dev/guide/migrate

Execute the migration command. It can be run without arguments to migrate the current directory or with a path to migrate a specific target directory.

```bash
vp migrate
vp migrate <path>
vp migrate --no-interactive
```

```bash
vp migrate
vp migrate my-app
```

--------------------------------

### Inspect Templates Non-Interactively

Source: https://viteplus.dev/guide/create

Use the `--no-interactive` flag with `vp create` to print a manifest table of available templates. This is useful for scripting or CI environments. An error is printed if a template name is required but not provided.

```bash
vp create @org --no-interactive
```

```bash
vp create @your-org:web --no-interactive
```

```bash
vp create vite:application --no-interactive
```

--------------------------------

### Registering Local Generators in Vite+ Config

Source: https://viteplus.dev/guide/create

Example of how to register a local generator in the 'create.templates' section of vite.config.ts. This ensures the generator appears in the 'vp create' picker. Re-running the scaffold command is idempotent.

```typescript
import { defineConfig } from 'vite-plus';

export default defineConfig({
  create: {
    templates: [
      { name: 'my-generator', description: 'Generate new components', template: 'my-generator' },
    ],
  },
});
```

--------------------------------

### Basic Linting Commands

Source: https://viteplus.dev/guide/lint

Run `vp lint` to perform a standard linting check. Use `vp lint --fix` to automatically fix linting issues. Add `--type-aware` for rules requiring type information.

```bash
vp lint
vp lint --fix
vp lint --type-aware
```

--------------------------------

### Migrate Current Project with VitePlus CLI

Source: https://viteplus.dev/guide/migrate

Use this command to initiate a migration for the project in the current directory.

```bash
# Migrate the current project
vp migrate
```

--------------------------------

### Configure Staged File Checks in Vite+

Source: https://viteplus.dev/guide/commit-hooks

Define staged-file checks in the `staged` block within `vite.config.ts`. This configuration replaces separate `lint-staged` setups and keeps all staged-file check configurations in one place.

```typescript
import { defineConfig } from 'vite-plus';

export default defineConfig({
  staged: {
    '*.{js,ts,tsx,vue,svelte}': 'vp check --fix',
  },
});
```

--------------------------------

### Vite+ Docker Image Tags

Source: https://viteplus.dev/guide/docker

Understand the available tags for the Vite+ Docker image, which correspond to different versions of the `vp` CLI.

```bash
ghcr.io/voidzero-dev/vite-plus:latest
```

```bash
ghcr.io/voidzero-dev/vite-plus:<major>
```

```bash
ghcr.io/voidzero-dev/vite-plus:<major>.<minor>
```

```bash
ghcr.io/voidzero-dev/vite-plus:<major>.<minor>.<patch>
```

--------------------------------

### Run Binary with vpx

Source: https://viteplus.dev/guide/vpx

Execute any local or remote npm package binary. It can download packages on demand if not found locally.

```bash
vpx <pkg[@version]> [args...]
```

--------------------------------

### Task Configuration with Input and Output

Source: https://viteplus.dev/guide/cache

Configure a build task to use automatic input tracking and specify output files for cache restoration.

```typescript
tasks: {
  build: {
    command: 'node build.mjs',
    input: [{ auto: true }, '!dist/**'],
    output: ['dist/**'],
  },
}
```

--------------------------------

### Disable Managed Mode with vp env

Source: https://viteplus.dev/guide/env

Run this command to switch to system-first mode, where shims prefer your system Node.js and fall back to the Vite+-managed runtime only when necessary.

```bash
vp env off
```

--------------------------------

### Basic Task Configuration for File System Tracking

Source: https://viteplus.dev/guide/automatic-data-tracking

Configure a basic build task to enable automatic file system tracking. Vite Task will record source files, config files, and scanned directories.

```typescript
import {
  defineConfig
} from 'vite-plus';

export default defineConfig({
  run: {
    tasks: {
      build: {
        command: 'tsc',
      },
    },
  },
});
```

--------------------------------

### Show Detailed Execution Summary

Source: https://viteplus.dev/guide/run

Use the `-v` flag with the `vp run` command to display a detailed execution summary after tasks complete. This includes statistics and task-specific details.

```bash
vp run -r -v build
```

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Vite+ Task Runner • Execution Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Statistics:   3 tasks • 3 cache hits • 0 cache misses
Performance:  100% cache hit rate, 468ms saved in total

Task Details:
────────────────────────────────────────────────
  [1] @my/core#build: ~/packages/core$ vp build ✓
      → Cache hit - output replayed - 200ms saved
  ·······················································
  [2] @my/utils#build: ~/packages/utils$ vp build ✓
      → Cache hit - output replayed - 150ms saved
  ·······················································
  [3] @my/app#build: ~/packages/app$ vp build ✓
      → Cache hit - output replayed - 118ms saved
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

--------------------------------

### Bundled Organization Template Structure

Source: https://viteplus.dev/guide/create

This structure is recommended for most organizations, where all templates are located as subdirectories within the `@org/create` package. The manifest entries then use relative paths.

```bash
@your-org/create/
├── package.json              # "createConfig": { "templates": [{ "template": "./templates/web" }, ...] }
├── templates/
│   ├── web/
│   │   ├── package.json
│   │   └── src/...
│   └── library/...
└── README.md
```

--------------------------------

### Root Format Configuration with Overrides

Source: https://viteplus.dev/guide/monorepo

Configure default formatting options and apply package-specific overrides using 'fmt.overrides'. The 'options' key holds formatter-specific settings.

```typescript
import { defineConfig } from 'vite-plus';

export default defineConfig({
  fmt: {
    singleQuote: true,
    semi: true,
    overrides: [
      {
        files: ['apps/api/**'],
        options: {
          printWidth: 120,
        },
      },
      {
        files: ['**/*.md'],
        options: {
          proseWrap: 'always',
        },
      },
    ],
  },
});
```

--------------------------------

### Multi-stage Dockerfile for Vite+ SSR App

Source: https://viteplus.dev/guide/docker

This Dockerfile demonstrates a multi-stage build process. It first builds the application using the Vite+ toolchain image, then creates a minimal runtime image containing only Node.js and production dependencies.

```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 .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 .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"]

```

--------------------------------

### Migration Prompt for Vite+

Source: https://viteplus.dev/guide/migrate

Use this prompt when instructing a coding agent or for manual migration to Vite+. It includes pre-migration checks, the migration command, and post-migration verification steps.

```markdown
Migrate this project to Vite+. Vite+ replaces the current split tooling around runtime management, package management, dev/build/test commands, linting, formatting, and packaging. Run `vp help` to understand Vite+ capabilities and `vp help migrate` before making changes. Use `vp migrate --no-interactive` in the workspace root. Make sure the project is using Vite 8+ and Vitest 4.1+ before migrating.

After the migration:

- Confirm `vite` imports were rewritten to `vite-plus` where needed
- Confirm `vitest` imports were rewritten to `vite-plus/test` (and `@vitest/browser*` to `vite-plus/test/browser*`) where needed
- Remove old `vite`, `vitest`, and `@vitest/browser*` dependencies only after those rewrites are confirmed — `vite-plus` ships them as direct deps
- Move remaining tool-specific config into the appropriate blocks in `vite.config.ts`

Command mapping to keep in mind:

- `vp run <script>` is the equivalent of `pnpm run <script>`
- `vp test` runs the built-in test command, while `vp run test` runs the `test` script from `package.json`
- `vp install`, `vp add`, and `vp remove` delegate through the package manager declared by `packageManager`
- `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`, and `vp pack` replace the corresponding standalone tools
- Prefer `vp check` for validation loops

Finally, verify the migration by running: `vp install`, `vp check`, `vp test`, and `vp build`

Summarize the migration at the end and report any manual follow-up still required.
```

--------------------------------

### Create Project with Specific Template

Source: https://viteplus.dev/guide/create

Specify a template name to create a project based on that template. This can be a built-in template or a community/remote template.

```bash
vp create <template>
```

--------------------------------

### Run Vite+ Check Commands

Source: https://viteplus.dev/guide/check

Execute the `vp check` command for comprehensive static analysis. Use flags to modify its behavior, such as `--fix` to format and run autofixers, `--no-fmt` to skip formatting, `--no-lint` to skip linting, or a combination for specific checks.

```bash
vp check
vp check --fix             # Format and run autofixers.
vp check --no-fmt          # Skip format; run lint (and type-check if enabled).
vp check --no-lint         # Skip lint rules; keep type-check when enabled.
vp check --no-fmt --no-lint # Type-check only (requires `typeCheck` enabled).
```

--------------------------------

### Migrate Local `vite-plus` Package

Source: https://viteplus.dev/guide/upgrade

Run `vp migrate` to upgrade the local `vite-plus` package and associated toolchain versions within your project. This command re-pins `vite-plus`, the `vite` alias, and the `vitest` pin.

```bash
vp migrate
```

--------------------------------

### Running Workspace Scripts with Vite+

Source: https://viteplus.dev/guide/monorepo

Execute scripts across the entire workspace or specific packages using 'vp run'. Options include recursive execution, parallel processing, filtering, and caching.

```bash
vp run -r build
vp run -r --parallel dev
vp run --filter ./apps/web build
```

--------------------------------

### Local Package Linking

Source: https://viteplus.dev/guide/install

Manages local development links between packages.

```bash
vp link
```

```bash
vp unlink
```

--------------------------------

### Forwarding Template Options with Vite+

Source: https://viteplus.dev/guide/create

Pass arguments directly to the selected template by appending them after '--'. This is useful for templates that accept their own flags, such as specifying a Vite template.

```bash
vp create vite -- --template react-ts
```

--------------------------------

### Corepack Management with Vite+

Source: https://viteplus.dev/guide/env

Commands to enable or disable Corepack launchers for package managers like pnpm and yarn.

```bash
corepack enable               # pnpm and yarn now resolve via corepack
```

```bash
corepack disable              # Remove the pnpm/yarn launchers again
```

--------------------------------

### Organization Create Manifest Schema

Source: https://viteplus.dev/guide/create

The `createConfig.templates` manifest in `@org/create`'s `package.json` defines the available templates. Each entry requires a unique name, description, and a template specifier.

```json
{
  "name": "@your-org/create",
  "version": "1.0.0",
  "createConfig": {
    "templates": [
      {
        "name": "monorepo",
        "description": "Monorepo",
        "template": "@your-org/template-monorepo",
        "monorepo": true
      },
      {
        "name": "web",
        "description": "Web app template (Vite + React)",
        "template": "@your-org/template-web"
      },
      {
        "name": "demo",
        "description": "Bundled demo template",
        "template": "./templates/demo"
      }
    ]
  }
}
```