Task Caching

Vite Task can automatically track dependencies and cache tasks run through vp run.

Overview

When a task runs successfully (exit code 0), its terminal output (stdout/stderr) and all files it writes (output files) are saved. On the next run, Vite Task checks if anything changed:

1. Arguments: did the additional arguments passed to the task change?
2. Environment variables: did any fingerprinted env vars change?
3. Input files: did any file that the command reads change?

If the entry matches, Vite Task replays the terminal output, restores the written files, and skips the command.

When a cache miss occurs, Vite Task tells you exactly why:

$ vp lint ✗ cache miss: 'src/utils.ts' modified, executing
$ vp build ✗ cache miss: env 'VITE_GREETING' changed, executing
$ vp test ✗ cache miss: args changed, executing

When Is Caching Enabled?

A command run by vp run is either a task defined in vite.config.ts or a script defined in package.json. Task names and script names cannot overlap. By default, tasks are cached and scripts are not.

There are three types of controls for task caching, in order:

1. Per-task cache: false

A task can set cache: false to opt out. This cannot be overridden by any other cache control flag.

2. CLI flags

--no-cache disables caching for tasks and scripts. --cache enables caching for both tasks and scripts, which is equivalent to setting run.cache: true for that invocation.

3. Workspace config

The run.cache option in your root vite.config.ts controls the default for each category:

Setting	Default	Effect
cache.tasks	true	Cache tasks defined in vite.config.ts
cache.scripts	false	Cache package.json scripts

Automatic File Tracking

Vite Task tracks which files each command reads during execution. When a task runs, it records which files the process opens, such as your .ts source files, vite.config.ts, and package.json, and records their content hashes. On the next run, it re-checks those hashes to determine if anything changed.

This means caching works out of the box for most commands without any configuration. Vite Task also records:

• Missing files: if a command probes for a file that doesn't exist, such as utils.ts during module resolution, creating that file later correctly invalidates the cache.
• Directory listings: if a command scans a directory, such as a test runner looking for *.test.ts, adding or removing files in that directory invalidates the cache.

Avoiding Overly Broad Input Tracking

Automatic tracking can sometimes include more files than necessary, causing unnecessary cache misses:

• Tool cache files: some tools maintain their own cache, such as TypeScript's .tsbuildinfo or Cargo's target/. These files may change between runs even when your source code has not, causing unnecessary cache invalidation.
• Directory listings: when a command scans a directory, such as when globbing for **/*.js, Vite Task sees the directory read but not the glob pattern. Any file added or removed in that directory, even unrelated ones, invalidates the cache.

Use the input option to exclude files or to replace automatic tracking with explicit file patterns:

vite.config.ts

tasks: {
  build: {
    command: 'tsc',
    input: [{ auto: true }, '!**/*.tsbuildinfo'],
  },
}

Tool-Reported Caching

Tool-reported caching lets a tool report cache metadata to Vite Task while it runs. Vite+ supports this for vp build today, so standard Vite builds do not need manual env: ['VITE_*'] or output: ['dist/**'] config.

See Tool-Reported Caching for current support, manual config rules, and third-party tool integration.

Environment Variables

By default, tasks run in a clean environment. Only a small set of common variables, such as PATH, HOME, and CI, are passed through. Other environment variables are neither visible to the task nor included in the cache fingerprint.

To add an environment variable to the cache key, add it to env. Changing its value then invalidates the cache:

vite.config.ts

tasks: {
  build: {
    command: 'webpack --mode production',
    env: ['NODE_ENV'],
  },
}

To pass a variable to the task without affecting cache behavior, use untrackedEnv. This is useful for variables like CI or GITHUB_ACTIONS that should be available in the task, but do not affect caching behavior.

See Run Config for details on wildcard patterns and the full list of automatically passed-through variables.

Cache Sharing

Vite Task's cache is content-based. If two tasks run the same command with the same inputs, they share the cache entry. This happens naturally when multiple tasks include a common step, either as standalone tasks or as parts of compound commands:

package.json

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

With caching enabled, for example through --cache or run.cache.scripts: true, running check first means the vp lint step in release is an instant cache hit, since both run the same command against the same files.

Cache Commands

Use vp cache clean when you need to clear cached task results:

vp cache clean

The task cache is stored in node_modules/.vite/task-cache at the project root. vp cache clean deletes that cache directory.