From 2cde346761a66a0f1ece8410d22a392a7ba6fb5f Mon Sep 17 00:00:00 2001 From: wan9chi Date: Mon, 29 Jun 2026 11:12:42 +0800 Subject: [PATCH 01/46] docs: add CI task cache guide Document GitHub Actions cache reuse for Vite Task, link it from the docs sidebar and CI guide, and update run/cache docs for output tracking and dependency task syntax. --- docs/.vitepress/config.mts | 4 + docs/config/run.md | 65 ++++++-- docs/guide/cache.md | 31 ++-- docs/guide/ci.md | 4 + docs/guide/github-actions-cache.md | 231 +++++++++++++++++++++++++++++ docs/guide/run.md | 34 ++++- 6 files changed, 338 insertions(+), 31 deletions(-) create mode 100644 docs/guide/github-actions-cache.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 200c0f922a..74aafda6c4 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -16,6 +16,10 @@ const taskRunnerGuideItems = [ text: 'Task Caching', link: '/guide/cache', }, + { + text: 'GitHub Actions Cache', + link: '/guide/github-actions-cache', + }, { text: 'Running Binaries', link: '/guide/vpx', diff --git a/docs/config/run.md b/docs/config/run.md index f4d7b6417d..025a56b398 100644 --- a/docs/config/run.md +++ b/docs/config/run.md @@ -120,9 +120,11 @@ Commands joined with `&&` (or supplied as an array) are automatically split into ### `dependsOn` -- **Type:** `string[]` +- **Type:** `Array` - **Default:** `[]` +`DependsOnFrom` accepts `"dependencies"`, `"devDependencies"`, `"peerDependencies"`, or an array of those values. + Tasks that must complete successfully before this one starts. ```ts [vite.config.ts] @@ -140,6 +142,19 @@ Dependencies can reference tasks in other packages using the `package#task` form dependsOn: ['@my/core#build', '@my/utils#lint']; ``` +Use the object form `{ task: string, from: DependsOnFrom }` to reference tasks from all dependencies: + +```ts [vite.config.ts] +tasks: { + test: { + command: 'vp test', + dependsOn: [{ task: 'build', from: ['dependencies', 'devDependencies'] }], + }, +} +``` + +For the example above, Vite Task reads the declaring package's direct `dependencies` and `devDependencies`, and runs `build` task in each dependency if it defines one. Packages without `build` are skipped. + See [Task Dependencies](/guide/run#task-dependencies) for details on how explicit and topological dependencies interact. ### `cache` @@ -168,17 +183,17 @@ Environment variables included in the cache fingerprint. When any listed variabl ```ts [vite.config.ts] tasks: { build: { - command: 'vp build', + command: 'node build.mjs', env: ['NODE_ENV'], }, } ``` -Wildcard patterns are supported: `VITE_*` matches all variables starting with `VITE_`. +Wildcard patterns and `!` exclusion patterns are supported: `VITE_*` matches all variables starting with `VITE_`, and `!VITE_SECRET` excludes the `VITE_SECRET` variable from the match. ```bash $ NODE_ENV=development vp run build # first run -$ NODE_ENV=production vp run build # cache miss: variable changed +$ NODE_ENV=production vp run build # cache miss: env 'NODE_ENV' changed ``` ### `untrackedEnv` @@ -191,13 +206,15 @@ Environment variables passed to the task process but **not** included in the cac ```ts [vite.config.ts] tasks: { build: { - command: 'vp build', + command: 'node build.mjs', untrackedEnv: ['CI', 'GITHUB_ACTIONS'], }, } ``` -A set of common environment variables are automatically passed through to all tasks: +`untrackedEnv` accepts the same wildcard and `!` exclusion patterns as [`env`](#env). + +Vite Task passes a set of common environment variables to all tasks: - **System:** `HOME`, `USER`, `PATH`, `SHELL`, `LANG`, `TZ` - **Node.js:** `NODE_OPTIONS`, `COREPACK_HOME`, `PNPM_HOME` @@ -270,26 +287,39 @@ String glob patterns are resolved relative to the package directory by default. ### `output` -- **Type:** `Array` -- **Default:** `[]` (nothing is archived) +- **Type:** `Array` +- **Default:** automatic write tracking + +Files Vite Task archives after a successful run and restores on a cache hit. -Files the task produces. They get archived after a successful run and restored on a cache hit, so you don't have to rebuild them. Leave it empty (or omit it) and nothing is archived. +If you omit `output`, Vite Task tracks files that the task writes and restores those files on cache hits. Use explicit output entries when you need to override the tracked files. ```ts [vite.config.ts] tasks: { build: { - command: 'vp build', + command: 'node build.mjs', output: ['dist/**', '!dist/cache/**'], }, } ``` +Use `{ auto: true }` to keep automatic write tracking while adding explicit output globs: + +```ts [vite.config.ts] +tasks: { + build: { + command: 'node build.mjs', + output: [{ auto: true }, 'storybook-static/**'], + }, +} +``` + If a task writes outside its own package, use the object form with `base: "workspace"`: ```ts [vite.config.ts] tasks: { build: { - command: 'vp build', + command: 'node build.mjs', output: [ 'dist/**', { pattern: 'shared-artifacts/**', base: 'workspace' }, @@ -298,6 +328,19 @@ tasks: { } ``` +Set `output: []` to disable output restoration for a cached task: + +```ts [vite.config.ts] +tasks: { + report: { + command: 'node scripts/report.mjs', + output: [], + }, +} +``` + +Vite Task still replays terminal output for that task on cache hits. + ### `cwd` - **Type:** `string` diff --git a/docs/guide/cache.md b/docs/guide/cache.md index fd034e0249..c121c14d9d 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -4,32 +4,19 @@ Vite Task can automatically track dependencies and cache tasks run through `vp r ## Overview -When a task runs successfully (exit code 0), its terminal output (stdout/stderr) is saved. On the next run, Vite Task checks if anything changed: +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](/guide/run#additional-arguments) passed to the task change? 2. **Environment variables:** did any [fingerprinted env vars](/config/run#env) change? 3. **Input files:** did any file that the command reads change? -If everything matches, the cached output is replayed instantly, and the command does not run. - -::: info -By default, only terminal output is cached and replayed. To cache files produced by a task, configure [`output`](/config/run#output) globs. Matching files are archived after a successful run and restored on a cache hit. -::: - -```ts [vite.config.ts] -tasks: { - build: { - command: 'vp build', - output: ['dist/**'], - }, -} -``` +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 changed, executing +$ vp build ✗ cache miss: env 'VITE_GREETING' changed, executing $ vp test ✗ cache miss: args changed, executing ``` @@ -45,7 +32,7 @@ A task can set [`cache: false`](/config/run#cache) to opt out. This cannot be ov ### 2. CLI flags -`--no-cache` disables caching for everything. `--cache` enables caching for both tasks and scripts, which is equivalent to setting [`run.cache: true`](/config/run#run-cache) for that invocation. +`--no-cache` disables caching for tasks and scripts. `--cache` enables caching for both tasks and scripts, which is equivalent to setting [`run.cache: true`](/config/run#run-cache) for that invocation. ### 3. Workspace config @@ -83,6 +70,14 @@ tasks: { } ``` +### Tool-Reported Caching + +Tool-reported caching lets a tool tell Vite Task which cache inputs, outputs, and environment variables affect its result. + +Vite+ only supports tool-reported caching for `vp build` today. Vite reports the build cache metadata it already knows, so you do not need to declare `env: ['VITE_*']` or replace automatic inputs for a standard Vite build. Add manual `input`, `output`, or `env` entries when your project has extra cache behavior the tool cannot know. + +We plan to extend tool-reported caching to more first-party tools. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). + ## 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. @@ -98,7 +93,7 @@ tasks: { } ``` -To pass a variable to the task **without** affecting cache behavior, use [`untrackedEnv`](/config/run#untracked-env). This is useful for variables like `CI` or `GITHUB_ACTIONS` that should be available in the task, but do not generally affect caching behavior. +To pass a variable to the task **without** affecting cache behavior, use [`untrackedEnv`](/config/run#untracked-env). 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](/config/run#env) for details on wildcard patterns and the full list of automatically passed-through variables. diff --git a/docs/guide/ci.md b/docs/guide/ci.md index ca958a3451..a11a99fa18 100644 --- a/docs/guide/ci.md +++ b/docs/guide/ci.md @@ -23,6 +23,10 @@ That means you usually do not need separate `setup-node`, package-manager setup, With `cache: true`, `setup-vp` handles dependency caching for you automatically. +::: tip +`setup-vp` caches package-manager data. To reuse Vite Task results across CI runs, add a separate [GitHub Actions cache for Vite Task](/guide/github-actions-cache). +::: + ## Simplifying Existing Workflows If you are migrating an existing GitHub Actions workflow, you can often replace large blocks of Node, package-manager, and cache setup with a single `setup-vp` step. diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md new file mode 100644 index 0000000000..b7d0225c25 --- /dev/null +++ b/docs/guide/github-actions-cache.md @@ -0,0 +1,231 @@ +# GitHub Actions Cache + +::: warning Experimental +Reusing Vite Task cache through GitHub Actions cache is experimental. Validate the workflow in your project before you depend on it for CI time savings. +::: + +Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. You can restore that directory in a later GitHub Actions run, then let Vite Task decide whether each task matches the current command, environment, inputs, and outputs. + +GitHub Actions cache and Vite Task make separate decisions: + +1. `actions/cache` restores and saves the cache directory based on the key in your workflow. +2. Vite Task checks the restored entries and replays only the tasks whose fingerprints still match. + +This cache is separate from dependency caching. Keep using [`setup-vp` cache support](/guide/ci) for package installs, then restore the Vite Task cache after dependencies are installed. + +## Before You Start + +Use this workflow when all of these are true: + +- The command runs through [`vp run`](/guide/run). +- The task hits on a second local run. +- The task has a stable input strategy for CI. +- The workflow installs dependencies before restoring `node_modules/.vite/task-cache`. + +Fix local misses first. GitHub Actions cache can move Vite Task's local cache directory between runs, but it cannot make an unstable task cacheable. + +## 1. Define Cacheable CI Tasks + +Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache; run `vp run build` or define a CI-specific task. + +The example below uses automatic input tracking for `vp build`. Vite reports build cache metadata to Vite Task through [tool-reported caching](/guide/cache#tool-reported-caching), so a short explicit list can miss files such as `public/**`, `.env*`, or framework config. The extra lockfile input ties the task fingerprint to dependency identity. + +The lint task uses explicit inputs because its CI input set is smaller. If you use npm, Yarn, or Bun, replace `pnpm-lock.yaml` with the lockfile your project commits. + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + 'ci-build': { + command: 'vp build', + input: [{ auto: true }, 'pnpm-lock.yaml', '!dist', '!dist/**'], + output: ['dist/**'], + }, + 'ci-lint': { + command: 'vp lint', + input: ['package.json', 'pnpm-lock.yaml', 'src/**', 'tsconfig*.json', 'vite.config.ts'], + }, + }, + }, +}); +``` + +The build task sets `output: ['dist/**']` to narrow output restoration to `dist`. The `!dist` input exclusions keep generated output files from invalidating the same cache entry Vite Task can restore. If you omit `output`, Vite Task tracks files that the task writes and restores those files on cache hits. Use [`output`](/config/run#output) when you need to narrow, extend, or disable output restoration. + +Run each task twice: + +```bash +vp run ci-build +vp run ci-build # should print "cache hit" +vp run ci-lint +vp run ci-lint # should print "cache hit" +``` + +For other auto-tracked tasks that produce files, use the same output pattern: + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + report: { + command: 'node scripts/report.mjs', + input: [{ auto: true }, '!reports', '!reports/**'], + output: ['reports/**'], + }, + }, + }, +}); +``` + +For a standard Vite build, you do not need to add `env: ['VITE_*']` or replace automatic inputs. Add explicit `input` entries only to track extra files such as lockfiles or to exclude generated outputs. + +## 2. Restore The Cache After Install + +Restore `node_modules/.vite/task-cache` after `vp install`, because package installation can recreate or modify `node_modules`. + +```yaml [.github/workflows/ci.yml] +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 }}-${{ hashFiles('**/pnpm-lock.yaml', '**/package-lock.json', '**/yarn.lock', '**/bun.lock', '**/bun.lockb') }}-${{ github.run_id }}-${{ github.run_attempt }} + restore-keys: | + vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml', '**/package-lock.json', '**/yarn.lock', '**/bun.lock', '**/bun.lockb') }}- + + - run: vp run ci-lint + - run: vp run ci-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 }} +``` + +The primary key includes `github.run_id` and `github.run_attempt` so each successful run can save a new immutable cache entry. The restore prefix includes the lockfile hash, so a dependency change starts from a cold Vite Task cache instead of restoring entries from a different dependency graph. + +Leave source files out of the GitHub Actions key. Vite Task fingerprints task inputs. If a source change updates the Actions key, GitHub can skip useful restores before Vite Task decides which tasks still hit. + +## 3. Verify In The Logs + +On the first run, the restore step should say that no cache was found, and the save step should create one. + +On a later run, look for both layers: + +```text +Cache restored from key: vite-task-Linux-X64-... +$ vp build ◉ cache hit, replaying +vp run: cache hit, 1.10s saved. +``` + +If GitHub restores a cache but Vite Task prints a cache miss, the Actions cache transport worked, but the task fingerprint changed. + +## 4. Workspaces + +Cache reuse works with workspace task targets. Define cacheable tasks in the package that owns the target, then run the same `vp run` command in CI: + +```bash +vp run -t @my/app#build +``` + +For workspace builds, keep automatic tracking and add the workspace lockfile as a workspace-relative input: + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + build: { + command: 'vp build', + dependsOn: [{ task: 'build', from: 'dependencies' }], + input: [ + { auto: true }, + { pattern: 'pnpm-lock.yaml', base: 'workspace' }, + '!dist', + '!dist/**', + ], + output: ['dist/**'], + }, + }, + }, +}); +``` + +The object-form `dependsOn` runs `build` in direct workspace dependency packages that define that task. Each dependency can pull in more tasks through its own `dependsOn` config. + +When the task cache is restored, Vite Task can replay hits for the target package and its workspace dependencies. In a transitive `core -> util -> app` experiment, restoring only `node_modules/.vite/task-cache` in a fresh checkout produced `3/3` cache hits and restored each package's `dist/**` output. + +## Keep Inputs Stable Across CI Runs + +Vite Task's [automatic input tracking](/guide/cache#automatic-file-tracking) records file reads, missing-file probes, and directory listings. In CI, a command can read files that describe the dependency install or tool state rather than source behavior. Those reads can change between runs and cause misses after a successful GitHub cache restore. + +Treat these cases by root cause: + +- **Dependency install metadata.** Package managers and build tools can read install metadata to resolve packages, discover workspace layout, or configure file-system access. Track dependency identity with committed package manifests and lockfiles. For `vp build`, keep automatic tracking and add the lockfile as an input. Use explicit `input` globs only for commands with a small input set you can name. +- **Tool-owned incremental state.** Tools such as TypeScript can write incremental state into a directory they also scan. A fresh checkout may lack that file, so the next run can miss because the directory listing changed. Move that state into a generated cache directory or use explicit task inputs. For TypeScript, set `--tsBuildInfoFile` to a generated cache location instead of writing `*.tsbuildinfo` next to source files. +- **Task outputs.** If a task output also appears in the input fingerprint, deleting the output causes a miss instead of an output restore. Keep generated files out of `input`, then let Vite Task restore tracked outputs. +- **Absolute arguments.** Vite Task stores command arguments in the fingerprint. If a command receives a different absolute checkout path between runs, it can miss with `args changed`. GitHub-hosted runners check out a repository under a stable path unless you override the checkout path. On self-hosted runners, keep the working directory stable or avoid absolute arguments. + +## Choose A Cache Key + +Use a rolling primary key plus a restore prefix: + +```yaml [.github/workflows/ci.yml] +key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml') }}-${{ github.run_id }}-${{ github.run_attempt }} +restore-keys: | + vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml') }}- +``` + +The exact key misses on each new run because the key contains `github.run_id` and `github.run_attempt`. GitHub then searches the restore prefix and restores the newest matching cache. Vite Task checks restored entries before replaying a task. + +Include: + +- `runner.os` and `runner.arch`, because outputs and native tools can be platform-specific. +- Your lockfile hash, so GitHub restores caches from the same dependency graph. +- A per-run value such as `github.run_id` and `github.run_attempt`, because GitHub cache entries are immutable. + +You can add a broader restore prefix only if the task inputs include the package manifests and lockfiles that define dependency identity. The broader prefix can save a download on some projects, but it can also restore a cache that Vite Task rejects task by task. + +## Limitations And Workarounds + +- **Cache entries are immutable.** Use a unique primary key per run and restore prefixes. GitHub will not update an existing cache entry in place. +- **GitHub evicts caches.** GitHub removes caches that have not been accessed for over 7 days. It also evicts least-recently-used entries when repository cache storage exceeds its limit, which defaults to 10 GB. If this causes churn, narrow what you cache, delete stale entries, or increase the repository cache limit in GitHub settings. +- **Cache scope is branch-aware.** Workflow runs can restore caches from the current branch and the default branch. Pull request merge-ref caches have limited scope and help re-runs of the same pull request. See [GitHub's dependency caching reference](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) for the full branch and tag rules. +- **Secrets can leak through cache contents.** Vite Task caches terminal output and configured output files. Keep secrets out of task logs and generated files that you cache. +- **Output tracking can be too broad or too narrow.** By default, Vite Task restores files that the task writes. Use `output` globs such as `['dist/**']` when you want to narrow restoration. Use `{ auto: true }` with extra globs when you want automatic write tracking plus extra files. +- **Failed tasks are not cached.** Vite Task saves successful task results. Fix failing lint, test, or build commands before expecting cache reuse. +- **Toolchain changes can start cold.** Vite Task uses schema-versioned cache directories. If a restored cache was written by an incompatible version, Vite Task ignores those entries and reruns the task. + +::: tip +Restore after dependency install because the default cache path lives under `node_modules`. If your workflow must restore before install, set a stable absolute `VITE_CACHE_PATH` outside `node_modules` for all `vp run` steps and cache that directory instead. +::: diff --git a/docs/guide/run.md b/docs/guide/run.md index 58d8350521..5c5fcac431 100644 --- a/docs/guide/run.md +++ b/docs/guide/run.md @@ -102,10 +102,40 @@ See [Run Config](/config/run) for the full `run` block reference. ## Task Dependencies -Use [`dependsOn`](/config/run#dependson) to run tasks in the right order. Running `vp run deploy` with the config above runs `build` and `test` first. Dependencies can also target other packages in the same project with the `package#task` notation: +Use [`dependsOn`](/config/run#dependson) to run tasks in the right order. Running `vp run deploy` with the config above runs `build` and `test` first. + +String task names in `dependsOn` reference tasks in the current or another package: + +```ts [vite.config.ts] +dependsOn: [ + 'build', // same package + '@my/core#build', // another package +]; +``` + +Use the object form when you need to reference all tasks with a given name from the current package's dependencies: + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + test: { + command: 'vp test', + dependsOn: [{ task: 'build', from: 'dependencies' }], + }, + }, + }, +}); +``` + +In this example, `vp run test` checks the current package's `dependencies`. For each direct workspace dependency that defines `build`, Vite Task runs that dependency's `build` task before `test`. + +Use an array when you need more than one dependency field: ```ts [vite.config.ts] -dependsOn: ['@my/core#build', '@my/utils#lint']; +dependsOn: [{ task: 'build', from: ['dependencies', 'devDependencies'] }]; ``` ## Running in a Workspace From 88f44b62d03ebe5366b3553294011f05be50655e Mon Sep 17 00:00:00 2001 From: wan9chi Date: Tue, 30 Jun 2026 00:49:03 +0800 Subject: [PATCH 02/46] docs: clarify tool-reported caching --- docs/guide/cache.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/guide/cache.md b/docs/guide/cache.md index c121c14d9d..2a1d2d653e 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -72,9 +72,15 @@ tasks: { ### Tool-Reported Caching -Tool-reported caching lets a tool tell Vite Task which cache inputs, outputs, and environment variables affect its result. +Tool-reported caching lets a tool report the cache facts it already knows at runtime, instead of making you copy tool-specific inputs, outputs, or environment variables into task config. -Vite+ only supports tool-reported caching for `vp build` today. Vite reports the build cache metadata it already knows, so you do not need to declare `env: ['VITE_*']` or replace automatic inputs for a standard Vite build. Add manual `input`, `output`, or `env` entries when your project has extra cache behavior the tool cannot know. +Vite+ currently supports tool-reported caching for `vp build`. When a task runs `vp build`, Vite reports the build cache metadata at runtime, so you do not need to declare `env: ['VITE_*']` or `output: ['dist/**']` for a standard Vite build. With task shorthand, the task can be: + +```ts [vite.config.ts] +tasks: { + build: 'vp build', +} +``` We plan to extend tool-reported caching to more first-party tools. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). From d258867b2afa9132fd12e0962f6460f51d8bf137 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Tue, 30 Jun 2026 10:36:23 +0800 Subject: [PATCH 03/46] docs: add tool-reported caching guide --- docs/.vitepress/config.mts | 4 ++ docs/config/run.md | 4 ++ docs/guide/cache.md | 14 ++---- docs/guide/github-actions-cache.md | 5 +- docs/guide/tool-reported-caching.md | 73 +++++++++++++++++++++++++++++ 5 files changed, 87 insertions(+), 13 deletions(-) create mode 100644 docs/guide/tool-reported-caching.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 74aafda6c4..2085df2d1a 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -16,6 +16,10 @@ const taskRunnerGuideItems = [ text: 'Task Caching', link: '/guide/cache', }, + { + text: 'Tool-Reported Caching', + link: '/guide/tool-reported-caching', + }, { text: 'GitHub Actions Cache', link: '/guide/github-actions-cache', diff --git a/docs/config/run.md b/docs/config/run.md index 025a56b398..fd122bcffb 100644 --- a/docs/config/run.md +++ b/docs/config/run.md @@ -191,6 +191,8 @@ tasks: { Wildcard patterns and `!` exclusion patterns are supported: `VITE_*` matches all variables starting with `VITE_`, and `!VITE_SECRET` excludes the `VITE_SECRET` variable from the match. +For `vp build`, Vite reports Vite environment variables through [tool-reported caching](/guide/tool-reported-caching). Do not add `VITE_*` or `NODE_ENV` here for a standard Vite build unless your project has extra build behavior Vite cannot report. + ```bash $ NODE_ENV=development vp run build # first run $ NODE_ENV=production vp run build # cache miss: env 'NODE_ENV' changed @@ -214,6 +216,8 @@ tasks: { `untrackedEnv` accepts the same wildcard and `!` exclusion patterns as [`env`](#env). +Do not put a variable in `untrackedEnv` if its value changes the task result. If a tool reports the variable through [tool-reported caching](/guide/tool-reported-caching), leave it out of both `env` and `untrackedEnv`. + Vite Task passes a set of common environment variables to all tasks: - **System:** `HOME`, `USER`, `PATH`, `SHELL`, `LANG`, `TZ` diff --git a/docs/guide/cache.md b/docs/guide/cache.md index 2a1d2d653e..3814d2473b 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -72,17 +72,9 @@ tasks: { ### Tool-Reported Caching -Tool-reported caching lets a tool report the cache facts it already knows at runtime, instead of making you copy tool-specific inputs, outputs, or environment variables into task config. +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. -Vite+ currently supports tool-reported caching for `vp build`. When a task runs `vp build`, Vite reports the build cache metadata at runtime, so you do not need to declare `env: ['VITE_*']` or `output: ['dist/**']` for a standard Vite build. With task shorthand, the task can be: - -```ts [vite.config.ts] -tasks: { - build: 'vp build', -} -``` - -We plan to extend tool-reported caching to more first-party tools. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). +See [Tool-Reported Caching](/guide/tool-reported-caching) for current support, manual config rules, and third-party tool integration. ## Environment Variables @@ -99,7 +91,7 @@ tasks: { } ``` -To pass a variable to the task **without** affecting cache behavior, use [`untrackedEnv`](/config/run#untracked-env). This is useful for variables like `CI` or `GITHUB_ACTIONS` that should be available in the task, but do not affect caching behavior. +To pass a variable to the task **without** affecting cache behavior, use [`untrackedEnv`](/config/run#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](/config/run#env) for details on wildcard patterns and the full list of automatically passed-through variables. diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index b7d0225c25..e1ed5e4527 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -28,7 +28,7 @@ Fix local misses first. GitHub Actions cache can move Vite Task's local cache di Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache; run `vp run build` or define a CI-specific task. -The example below uses automatic input tracking for `vp build`. Vite reports build cache metadata to Vite Task through [tool-reported caching](/guide/cache#tool-reported-caching), so a short explicit list can miss files such as `public/**`, `.env*`, or framework config. The extra lockfile input ties the task fingerprint to dependency identity. +The example below uses automatic input tracking for `vp build`. Vite reports build cache metadata to Vite Task through [tool-reported caching](/guide/tool-reported-caching), so a short explicit list can miss files such as `public/**`, `.env*`, or framework config. The extra lockfile input ties the task fingerprint to dependency identity. The lint task uses explicit inputs because its CI input set is smaller. If you use npm, Yarn, or Bun, replace `pnpm-lock.yaml` with the lockfile your project commits. @@ -137,7 +137,7 @@ Leave source files out of the GitHub Actions key. Vite Task fingerprints task in ## 3. Verify In The Logs -On the first run, the restore step should say that no cache was found, and the save step should create one. +On the first run, the restore step should say that no cache was found, and the save step should create one. Pull requests from forks may be restore-only because GitHub can give the cache token read-only access. In that case, the save step warns and exits successfully without writing a cache entry. On a later run, look for both layers: @@ -219,6 +219,7 @@ You can add a broader restore prefix only if the task inputs include the package ## Limitations And Workarounds - **Cache entries are immutable.** Use a unique primary key per run and restore prefixes. GitHub will not update an existing cache entry in place. +- **Fork pull requests may be restore-only.** GitHub can allow forked pull request runs to restore existing caches without saving new entries. Populate shared caches from trusted branch or default-branch runs. - **GitHub evicts caches.** GitHub removes caches that have not been accessed for over 7 days. It also evicts least-recently-used entries when repository cache storage exceeds its limit, which defaults to 10 GB. If this causes churn, narrow what you cache, delete stale entries, or increase the repository cache limit in GitHub settings. - **Cache scope is branch-aware.** Workflow runs can restore caches from the current branch and the default branch. Pull request merge-ref caches have limited scope and help re-runs of the same pull request. See [GitHub's dependency caching reference](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) for the full branch and tag rules. - **Secrets can leak through cache contents.** Vite Task caches terminal output and configured output files. Keep secrets out of task logs and generated files that you cache. diff --git a/docs/guide/tool-reported-caching.md b/docs/guide/tool-reported-caching.md new file mode 100644 index 0000000000..13d4ed88af --- /dev/null +++ b/docs/guide/tool-reported-caching.md @@ -0,0 +1,73 @@ +# Tool-Reported Caching + +Tool-reported caching lets a tool report cache metadata to Vite Task while it runs. The tool can report inputs, outputs, and environment variables that affect its result. + +Use this page when a tool can report cache behavior that task config should not duplicate. + +## Current Support + +Vite+ supports tool-reported caching for `vp build` today. + +When a task runs `vp build`, Vite reports build cache metadata to Vite Task. For a standard Vite build, you do not need to add these entries yourself: + +- `env: ['VITE_*']` or `env: ['NODE_ENV']` +- `output: ['dist/**']` +- explicit input globs that replace automatic input tracking + +Define the task through `vp run`: + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + build: 'vp build', + }, + }, +}); +``` + +Then run it with: + +```bash +vp run build +``` + +## When To Add Manual Config + +Tool-reported caching does not remove manual config. Add [`input`](/config/run#input), [`output`](/config/run#output), or [`env`](/config/run#env) when your project has behavior the tool cannot know. + +Common cases: + +- Add lockfiles or generated metadata that should affect [CI cache reuse](/guide/github-actions-cache). +- Exclude generated output directories from automatic inputs. +- Add custom environment variables that your own build wrapper reads. + +For example, a CI build can keep automatic inputs and add the lockfile: + +```ts [vite.config.ts] +build: { + command: 'vp build', + input: [{ auto: true }, 'pnpm-lock.yaml', '!dist', '!dist/**'], + output: ['dist/**'], +} +``` + +## Environment Variables + +For `vp build`, Vite reports the Vite environment variables that affect the build. Do not add `VITE_*` or `NODE_ENV` to [`env`](/config/run#env) or [`untrackedEnv`](/config/run#untrackedenv) for a standard Vite build. + +For other commands, use `env` when a variable changes the result, and use `untrackedEnv` only when the task needs the variable but the value does not affect cache behavior. + +## Third-Party Tools + +Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). + +Tool-reported caching works with Vite Task's [automatic file tracking](/guide/cache#automatic-file-tracking). Vite Task still observes file reads and writes, and the tool report adds metadata the tool knows at runtime. + +## Future Support + +Vite+ will add tool-reported caching to more first-party tools as those integrations are built. + +Until a tool supports tool-reported caching, configure cache behavior with [`input`](/config/run#input), [`output`](/config/run#output), and [`env`](/config/run#env). From 33a293e1645e756cc0ee23165c239054ed16b3a4 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Tue, 30 Jun 2026 23:49:01 +0800 Subject: [PATCH 04/46] docs: remove redundant setup-vp cache flag --- docs/guide/github-actions-cache.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index e1ed5e4527..7184ecf126 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -107,7 +107,6 @@ jobs: - uses: voidzero-dev/setup-vp@v1 with: node-version: '24' - cache: true - run: vp install From 583aa1a40ba3f3dce16946b8bbc1858e50f20314 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 00:02:47 +0800 Subject: [PATCH 05/46] docs: unify automatic tracking guidance --- docs/.vitepress/config.mts | 4 +- docs/config/run.md | 6 +- docs/guide/automatic-tracking.md | 148 ++++++++++++++++++++++++++++ docs/guide/cache.md | 25 ++--- docs/guide/github-actions-cache.md | 6 +- docs/guide/run.md | 2 +- docs/guide/tool-reported-caching.md | 73 -------------- 7 files changed, 163 insertions(+), 101 deletions(-) create mode 100644 docs/guide/automatic-tracking.md delete mode 100644 docs/guide/tool-reported-caching.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 2085df2d1a..ab43ee2122 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -17,8 +17,8 @@ const taskRunnerGuideItems = [ link: '/guide/cache', }, { - text: 'Tool-Reported Caching', - link: '/guide/tool-reported-caching', + text: 'Automatic Tracking', + link: '/guide/automatic-tracking', }, { text: 'GitHub Actions Cache', diff --git a/docs/config/run.md b/docs/config/run.md index fd122bcffb..9b9c7c934e 100644 --- a/docs/config/run.md +++ b/docs/config/run.md @@ -191,7 +191,7 @@ tasks: { Wildcard patterns and `!` exclusion patterns are supported: `VITE_*` matches all variables starting with `VITE_`, and `!VITE_SECRET` excludes the `VITE_SECRET` variable from the match. -For `vp build`, Vite reports Vite environment variables through [tool-reported caching](/guide/tool-reported-caching). Do not add `VITE_*` or `NODE_ENV` here for a standard Vite build unless your project has extra build behavior Vite cannot report. +For `vp build`, Vite reports Vite environment variables through [automatic tracking](/guide/automatic-tracking#cooperative-tracking). Do not add `VITE_*` or `NODE_ENV` here for a standard Vite build unless your project has extra build behavior Vite cannot report. ```bash $ NODE_ENV=development vp run build # first run @@ -216,7 +216,7 @@ tasks: { `untrackedEnv` accepts the same wildcard and `!` exclusion patterns as [`env`](#env). -Do not put a variable in `untrackedEnv` if its value changes the task result. If a tool reports the variable through [tool-reported caching](/guide/tool-reported-caching), leave it out of both `env` and `untrackedEnv`. +Do not put a variable in `untrackedEnv` if its value changes the task result. If a cache-reporting tool covers the variable through [automatic tracking](/guide/automatic-tracking#cooperative-tracking), leave it out of both `env` and `untrackedEnv`. Vite Task passes a set of common environment variables to all tasks: @@ -230,7 +230,7 @@ Vite Task passes a set of common environment variables to all tasks: - **Type:** `Array` - **Default:** `[{ auto: true }]` (auto-inferred) -Vite Task automatically detects which files are used by a command (see [Automatic File Tracking](/guide/cache#automatic-file-tracking)). The `input` option can be used to explicitly include or exclude certain files. +Vite Task automatically detects which files a command uses. See [Automatic Tracking](/guide/automatic-tracking) for the two tracking tiers and when to add manual config. The `input` option can be used to explicitly include or exclude certain files. **Exclude files** from automatic tracking: diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md new file mode 100644 index 0000000000..24ec189390 --- /dev/null +++ b/docs/guide/automatic-tracking.md @@ -0,0 +1,148 @@ +# Automatic Tracking + +Automatic tracking is how Vite Task learns whether a cached task can be reused. When you run a cached command through `vp run`, Vite Task records the files, outputs, and cache-reporting metadata that affect the result. On the next run, Vite Task compares that record with the current command and replays the task only when the fingerprint still matches. + +Use this page when you need to understand why a task hits or misses the cache, or when you need to decide whether to add `input`, `output`, `env`, or `untrackedEnv` config. + +## Tracking Tiers + +Automatic tracking has two tiers: + +| Tier | Applies to | Records | +| -------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| File system tracking | All cached tasks run through `vp run` | Files read by the command, missing-file probes, directory listings, and written output files | +| Cooperative tracking | Cache-reporting tools | Metadata reported by the tool, such as environment variables and tool-owned paths that should not affect the task result | + +Vite Task starts with file system tracking for any command. A cache-reporting tool can add information that only the tool knows while it runs. + +## File System Tracking + +File system tracking applies to every cached task run through `vp run`. If you omit [`input`](/config/run#input), Vite Task tracks the files a command reads while it runs: + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + build: { + command: 'tsc', + }, + }, + }, +}); +``` + +For this task, Vite Task records source files, config files, missing files the command checked, and directories the command scanned. A later run misses the cache when one of those tracked inputs changes. + +File system tracking also tracks outputs. If you omit [`output`](/config/run#output), Vite Task archives files the command writes after a successful run and restores them on a cache hit. + +### Adjust File System Tracking + +Keep file system tracking and add exclusions when a command reads generated files that should not invalidate the task: + +```ts [vite.config.ts] +tasks: { + build: { + command: 'tsc', + input: [{ auto: true }, '!**/*.tsbuildinfo', '!dist', '!dist/**'], + }, +} +``` + +Use explicit `input` globs only when the command has a small, stable input set you can name: + +```ts [vite.config.ts] +tasks: { + lint: { + command: 'vp lint', + input: ['package.json', 'pnpm-lock.yaml', 'src/**', 'tsconfig*.json'], + }, +} +``` + +Use explicit `output` globs when you want to narrow or extend the files Vite Task restores: + +```ts [vite.config.ts] +tasks: { + build: { + command: 'node build.mjs', + output: ['dist/**'], + }, +} +``` + +Set `input: []` to disable file tracking for a task. Set `output: []` to disable output restoration. The task can still use cache entries based on command arguments and tracked environment variables. + +## Cooperative Tracking + +Some tools know cache dependencies that file system tracking cannot infer from the outside. A cache-reporting tool can cooperate with Vite Task while it runs. Vite Task still observes file reads and writes. It uses the report to refine the cache fingerprint. + +Vite+ supports cooperative tracking for `vp build` today. When a task runs `vp build`, Vite reports build cache metadata to Vite Task. For a standard Vite build, you do not need to add these entries yourself: + +- `env: ['VITE_*']` or `env: ['NODE_ENV']` +- `output: ['dist/**']` +- explicit input globs that replace file system tracking + +Define the build as a `vp run` task: + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + build: 'vp build', + }, + }, +}); +``` + +Then run it with: + +```bash +vp run build +``` + +Direct `vp build` runs a build, but it does not use the Vite Task cache. Use `vp run build` when you want task caching. + +Vite+ will extend cooperative tracking to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). + +## When To Add Manual Config + +Add config when your project has behavior the command or tool cannot know. + +| Goal | Config | +| -------------------------------------------------------- | ---------------------------------------------- | +| Keep file system tracking and add CI dependency identity | `input: [{ auto: true }, 'pnpm-lock.yaml']` | +| Exclude generated output from the input fingerprint | `input: [{ auto: true }, '!dist', '!dist/**']` | +| Replace file system tracking for a small input set | `input: ['src/**', 'package.json']` | +| Narrow output restoration | `output: ['dist/**']` | +| Track an env var used by a non-reporting command | `env: ['NODE_ENV']` | +| Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` | + +For CI builds, keep automatic tracking for `vp build` and add only the extra project facts CI needs: + +```ts [vite.config.ts] +tasks: { + 'ci-build': { + command: 'vp build', + input: [{ auto: true }, 'pnpm-lock.yaml', '!dist', '!dist/**'], + output: ['dist/**'], + }, +} +``` + +This task keeps file system tracking, lets Vite report build metadata, adds the lockfile to the fingerprint, excludes restored output files from inputs, and restores only `dist/**` on a cache hit. + +## Common Cache Miss Causes + +Vite Task chooses a cache miss when tracked data changed between runs. In CI, these data sources often explain misses after a restored cache: + +- **Dependency install metadata:** add committed package manifests and lockfiles as inputs. For `vp build`, keep automatic tracking and add the lockfile. +- **Tool-owned incremental state:** move incremental files into a generated cache directory or exclude them from file system-tracked inputs. +- **Generated outputs:** exclude output directories from `input`, then configure `output` so Vite Task can restore them. +- **Broad directory scans:** use explicit `input` globs when a command scans directories that contain unrelated files. +- **Environment variables:** add `env` for variables that change a non-reporting command's result. Leave standard Vite build env vars out of `env` because `vp build` reports them. + +For GitHub Actions cache reuse, see [GitHub Actions Cache](/guide/github-actions-cache). That guide explains how to restore `node_modules/.vite/task-cache` between CI runs after your task hits locally. diff --git a/docs/guide/cache.md b/docs/guide/cache.md index 3814d2473b..fd3f2bd305 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -8,7 +8,7 @@ When a task runs successfully (exit code 0), its terminal output (stdout/stderr) 1. **Arguments:** did the [additional arguments](/guide/run#additional-arguments) passed to the task change? 2. **Environment variables:** did any [fingerprinted env vars](/config/run#env) change? -3. **Input files:** did any file that the command reads change? +3. **Inputs:** did any tracked file or cache-reporting dependency change? If the entry matches, Vite Task replays the terminal output, restores the written files, and skips the command. @@ -43,21 +43,12 @@ The [`run.cache`](/config/run#run-cache) option in your root `vite.config.ts` co | `cache.tasks` | `true` | Cache tasks defined in `vite.config.ts` | | `cache.scripts` | `false` | Cache `package.json` scripts | -## Automatic File Tracking +## Automatic 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. +Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn what each cached task depends on. Automatic tracking has two tiers: -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. +- **File system tracking:** Vite Task records file reads, missing-file probes, directory listings, and written output files for every cached task run through `vp run`. +- **Cooperative tracking:** cache-reporting tools can report metadata that file system tracking cannot infer. Vite+ supports this for `vp build` today. Use the [`input`](/config/run#input) option to exclude files or to replace automatic tracking with explicit file patterns: @@ -70,11 +61,7 @@ tasks: { } ``` -### 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](/guide/tool-reported-caching) for current support, manual config rules, and third-party tool integration. +See [Automatic Tracking](/guide/automatic-tracking) for current `vp build` support, CI guidance, and third-party tool integration. ## Environment Variables diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index 7184ecf126..6ca88b1f98 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -28,7 +28,7 @@ Fix local misses first. GitHub Actions cache can move Vite Task's local cache di Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache; run `vp run build` or define a CI-specific task. -The example below uses automatic input tracking for `vp build`. Vite reports build cache metadata to Vite Task through [tool-reported caching](/guide/tool-reported-caching), so a short explicit list can miss files such as `public/**`, `.env*`, or framework config. The extra lockfile input ties the task fingerprint to dependency identity. +The example below uses [automatic tracking](/guide/automatic-tracking) for `vp build`. Vite Task tracks file reads, and Vite reports build metadata that file tracking cannot infer. A short explicit input list can miss files such as `public/**`, `.env*`, or framework config. The extra lockfile input ties the task fingerprint to dependency identity. The lint task uses explicit inputs because its CI input set is smaller. If you use npm, Yarn, or Bun, replace `pnpm-lock.yaml` with the lockfile your project commits. @@ -81,7 +81,7 @@ export default defineConfig({ }); ``` -For a standard Vite build, you do not need to add `env: ['VITE_*']` or replace automatic inputs. Add explicit `input` entries only to track extra files such as lockfiles or to exclude generated outputs. +For a standard Vite build, you do not need to add `env: ['VITE_*']` or replace automatic tracking. Add explicit `input` entries only to track extra files such as lockfiles or to exclude generated outputs. ## 2. Restore The Cache After Install @@ -186,7 +186,7 @@ When the task cache is restored, Vite Task can replay hits for the target packag ## Keep Inputs Stable Across CI Runs -Vite Task's [automatic input tracking](/guide/cache#automatic-file-tracking) records file reads, missing-file probes, and directory listings. In CI, a command can read files that describe the dependency install or tool state rather than source behavior. Those reads can change between runs and cause misses after a successful GitHub cache restore. +Vite Task's [automatic tracking](/guide/automatic-tracking) records file reads, missing-file probes, and directory listings. In CI, a command can read files that describe the dependency install or tool state rather than source behavior. Those reads can change between runs and cause misses after a successful GitHub cache restore. Treat these cases by root cause: diff --git a/docs/guide/run.md b/docs/guide/run.md index 5c5fcac431..e797c37ece 100644 --- a/docs/guide/run.md +++ b/docs/guide/run.md @@ -69,7 +69,7 @@ $ node compile-legacy-app.js ✗ cache miss: 'legacy/index.js' modified, executi ## Task Definitions -Vite Task automatically tracks which files your command uses. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior. +Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn which files, outputs, and cache-reporting metadata your command uses. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior. ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; diff --git a/docs/guide/tool-reported-caching.md b/docs/guide/tool-reported-caching.md deleted file mode 100644 index 13d4ed88af..0000000000 --- a/docs/guide/tool-reported-caching.md +++ /dev/null @@ -1,73 +0,0 @@ -# Tool-Reported Caching - -Tool-reported caching lets a tool report cache metadata to Vite Task while it runs. The tool can report inputs, outputs, and environment variables that affect its result. - -Use this page when a tool can report cache behavior that task config should not duplicate. - -## Current Support - -Vite+ supports tool-reported caching for `vp build` today. - -When a task runs `vp build`, Vite reports build cache metadata to Vite Task. For a standard Vite build, you do not need to add these entries yourself: - -- `env: ['VITE_*']` or `env: ['NODE_ENV']` -- `output: ['dist/**']` -- explicit input globs that replace automatic input tracking - -Define the task through `vp run`: - -```ts [vite.config.ts] -import { defineConfig } from 'vite-plus'; - -export default defineConfig({ - run: { - tasks: { - build: 'vp build', - }, - }, -}); -``` - -Then run it with: - -```bash -vp run build -``` - -## When To Add Manual Config - -Tool-reported caching does not remove manual config. Add [`input`](/config/run#input), [`output`](/config/run#output), or [`env`](/config/run#env) when your project has behavior the tool cannot know. - -Common cases: - -- Add lockfiles or generated metadata that should affect [CI cache reuse](/guide/github-actions-cache). -- Exclude generated output directories from automatic inputs. -- Add custom environment variables that your own build wrapper reads. - -For example, a CI build can keep automatic inputs and add the lockfile: - -```ts [vite.config.ts] -build: { - command: 'vp build', - input: [{ auto: true }, 'pnpm-lock.yaml', '!dist', '!dist/**'], - output: ['dist/**'], -} -``` - -## Environment Variables - -For `vp build`, Vite reports the Vite environment variables that affect the build. Do not add `VITE_*` or `NODE_ENV` to [`env`](/config/run#env) or [`untrackedEnv`](/config/run#untrackedenv) for a standard Vite build. - -For other commands, use `env` when a variable changes the result, and use `untrackedEnv` only when the task needs the variable but the value does not affect cache behavior. - -## Third-Party Tools - -Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). - -Tool-reported caching works with Vite Task's [automatic file tracking](/guide/cache#automatic-file-tracking). Vite Task still observes file reads and writes, and the tool report adds metadata the tool knows at runtime. - -## Future Support - -Vite+ will add tool-reported caching to more first-party tools as those integrations are built. - -Until a tool supports tool-reported caching, configure cache behavior with [`input`](/config/run#input), [`output`](/config/run#output), and [`env`](/config/run#env). From 4dc8fed7aa5b9edbd055cf7dbc302925529a0d37 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 00:51:38 +0800 Subject: [PATCH 06/46] docs: simplify task cache wording --- docs/guide/cache.md | 6 +++--- docs/guide/run.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide/cache.md b/docs/guide/cache.md index fd3f2bd305..8496637182 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -8,9 +8,9 @@ When a task runs successfully (exit code 0), its terminal output (stdout/stderr) 1. **Arguments:** did the [additional arguments](/guide/run#additional-arguments) passed to the task change? 2. **Environment variables:** did any [fingerprinted env vars](/config/run#env) change? -3. **Inputs:** did any tracked file or cache-reporting dependency change? +3. **Inputs:** did any input 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 all checks match, Vite Task replays the cached terminal output, restores saved output files, and skips the command. When a cache miss occurs, Vite Task tells you exactly why: @@ -32,7 +32,7 @@ A task can set [`cache: false`](/config/run#cache) to opt out. This cannot be ov ### 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`](/config/run#run-cache) for that invocation. +`--no-cache` disables caching for every task and script in that run. `--cache` enables caching for both tasks and scripts, which is equivalent to setting [`run.cache: true`](/config/run#run-cache) for that invocation. ### 3. Workspace config diff --git a/docs/guide/run.md b/docs/guide/run.md index e797c37ece..a2721ea8f2 100644 --- a/docs/guide/run.md +++ b/docs/guide/run.md @@ -69,7 +69,7 @@ $ node compile-legacy-app.js ✗ cache miss: 'legacy/index.js' modified, executi ## Task Definitions -Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn which files, outputs, and cache-reporting metadata your command uses. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior. +Vite Task [automatically tracks](/guide/automatic-tracking) the data needed to cache your tasks. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior. ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; From 9baaab1ea53f81b1ebf4a34888a6f2421793bef1 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 00:58:13 +0800 Subject: [PATCH 07/46] docs: refine automatic tracking wording --- docs/guide/run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/run.md b/docs/guide/run.md index a2721ea8f2..cf3be3d2f8 100644 --- a/docs/guide/run.md +++ b/docs/guide/run.md @@ -69,7 +69,7 @@ $ node compile-legacy-app.js ✗ cache miss: 'legacy/index.js' modified, executi ## Task Definitions -Vite Task [automatically tracks](/guide/automatic-tracking) the data needed to cache your tasks. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior. +Vite Task [automatically tracks](/guide/automatic-tracking) what each task needs for caching. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior. ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; From f4bcb26a852134e730950741fa0d16468c46b8f7 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:01:49 +0800 Subject: [PATCH 08/46] docs: remove redundant tracking link --- docs/guide/cache.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/guide/cache.md b/docs/guide/cache.md index 8496637182..22986878fa 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -61,8 +61,6 @@ tasks: { } ``` -See [Automatic Tracking](/guide/automatic-tracking) for current `vp build` support, CI guidance, 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. From dfabfbbe28d717b6a8b74af56eb9947143ea9955 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:08:52 +0800 Subject: [PATCH 09/46] docs: pair input and output tracking guidance --- docs/config/run.md | 4 ++-- docs/guide/automatic-tracking.md | 16 +++++++++------- docs/guide/cache.md | 11 ++++++----- docs/guide/github-actions-cache.md | 10 +++++----- 4 files changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/config/run.md b/docs/config/run.md index 9b9c7c934e..857f277922 100644 --- a/docs/config/run.md +++ b/docs/config/run.md @@ -230,7 +230,7 @@ Vite Task passes a set of common environment variables to all tasks: - **Type:** `Array` - **Default:** `[{ auto: true }]` (auto-inferred) -Vite Task automatically detects which files a command uses. See [Automatic Tracking](/guide/automatic-tracking) for the two tracking tiers and when to add manual config. The `input` option can be used to explicitly include or exclude certain files. +Vite Task automatically detects which files a command uses. See [Automatic Tracking](/guide/automatic-tracking) for the two tracking tiers and when to add manual config. The `input` option explicitly includes or excludes files from the cache fingerprint. Pair it with [`output`](#output) when a task writes files that Vite Task should restore. **Exclude files** from automatic tracking: @@ -294,7 +294,7 @@ String glob patterns are resolved relative to the package directory by default. - **Type:** `Array` - **Default:** automatic write tracking -Files Vite Task archives after a successful run and restores on a cache hit. +Files Vite Task archives after a successful run and restores on a cache hit. Pair `output` with [`input`](#input) when a task writes files that it also reads, so generated files do not invalidate the cache entry Vite Task can restore. If you omit `output`, Vite Task tracks files that the task writes and restores those files on cache hits. Use explicit output entries when you need to override the tracked files. diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 24ec189390..e7258ccb1d 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -37,20 +37,21 @@ For this task, Vite Task records source files, config files, missing files the c File system tracking also tracks outputs. If you omit [`output`](/config/run#output), Vite Task archives files the command writes after a successful run and restores them on a cache hit. -### Adjust File System Tracking +### Override Inputs And Outputs -Keep file system tracking and add exclusions when a command reads generated files that should not invalidate the task: +Pair input and output overrides when a task writes files. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. ```ts [vite.config.ts] tasks: { build: { - command: 'tsc', - input: [{ auto: true }, '!**/*.tsbuildinfo', '!dist', '!dist/**'], + command: 'node build.mjs', + input: [{ auto: true }, '!dist', '!dist/**'], + output: ['dist/**'], }, } ``` -Use explicit `input` globs only when the command has a small, stable input set you can name: +Use explicit `input` globs only when the command has a small, stable input set you can name. Commands that do not write outputs do not need `output`: ```ts [vite.config.ts] tasks: { @@ -61,12 +62,13 @@ tasks: { } ``` -Use explicit `output` globs when you want to narrow or extend the files Vite Task restores: +Use explicit `output` globs when you want to narrow or extend the files Vite Task restores. If the command also reads its output directory, exclude that directory from `input`: ```ts [vite.config.ts] tasks: { build: { command: 'node build.mjs', + input: [{ auto: true }, '!dist', '!dist/**'], output: ['dist/**'], }, } @@ -142,7 +144,7 @@ Vite Task chooses a cache miss when tracked data changed between runs. In CI, th - **Dependency install metadata:** add committed package manifests and lockfiles as inputs. For `vp build`, keep automatic tracking and add the lockfile. - **Tool-owned incremental state:** move incremental files into a generated cache directory or exclude them from file system-tracked inputs. - **Generated outputs:** exclude output directories from `input`, then configure `output` so Vite Task can restore them. -- **Broad directory scans:** use explicit `input` globs when a command scans directories that contain unrelated files. +- **Broad directory scans:** use explicit `input` globs when a command scans directories that contain unrelated files. If the command writes files, review `output` in the same task config. - **Environment variables:** add `env` for variables that change a non-reporting command's result. Leave standard Vite build env vars out of `env` because `vp build` reports them. For GitHub Actions cache reuse, see [GitHub Actions Cache](/guide/github-actions-cache). That guide explains how to restore `node_modules/.vite/task-cache` between CI runs after your task hits locally. diff --git a/docs/guide/cache.md b/docs/guide/cache.md index 22986878fa..469ed87802 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -45,18 +45,19 @@ The [`run.cache`](/config/run#run-cache) option in your root `vite.config.ts` co ## Automatic Tracking -Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn what each cached task depends on. Automatic tracking has two tiers: +Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn what each task needs for caching, so most tasks do not need manual tracking rules. Automatic tracking has two tiers: -- **File system tracking:** Vite Task records file reads, missing-file probes, directory listings, and written output files for every cached task run through `vp run`. +- **File system tracking:** Vite Task records file reads, missing-file probes, directory listings, and written output files for every task with cache enabled. - **Cooperative tracking:** cache-reporting tools can report metadata that file system tracking cannot infer. Vite+ supports this for `vp build` today. -Use the [`input`](/config/run#input) option to exclude files or to replace automatic tracking with explicit file patterns: +Use [`input`](/config/run#input) and [`output`](/config/run#output) together when a task needs manual tracking rules. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. ```ts [vite.config.ts] tasks: { build: { - command: 'tsc', - input: [{ auto: true }, '!**/*.tsbuildinfo'], + command: 'node build.mjs', + input: [{ auto: true }, '!dist', '!dist/**'], + output: ['dist/**'], }, } ``` diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index 6ca88b1f98..6d0d94a7b7 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -19,7 +19,7 @@ Use this workflow when all of these are true: - The command runs through [`vp run`](/guide/run). - The task hits on a second local run. -- The task has a stable input strategy for CI. +- The task has stable input and output tracking for CI. - The workflow installs dependencies before restoring `node_modules/.vite/task-cache`. Fix local misses first. GitHub Actions cache can move Vite Task's local cache directory between runs, but it cannot make an unstable task cacheable. @@ -81,7 +81,7 @@ export default defineConfig({ }); ``` -For a standard Vite build, you do not need to add `env: ['VITE_*']` or replace automatic tracking. Add explicit `input` entries only to track extra files such as lockfiles or to exclude generated outputs. +For a standard Vite build, you do not need to add `env: ['VITE_*']` or replace automatic tracking. Add explicit `input` entries only to track extra files such as lockfiles or to exclude generated outputs. Add explicit `output` entries only when you need to narrow, extend, or disable output restoration. ## 2. Restore The Cache After Install @@ -184,15 +184,15 @@ The object-form `dependsOn` runs `build` in direct workspace dependency packages When the task cache is restored, Vite Task can replay hits for the target package and its workspace dependencies. In a transitive `core -> util -> app` experiment, restoring only `node_modules/.vite/task-cache` in a fresh checkout produced `3/3` cache hits and restored each package's `dist/**` output. -## Keep Inputs Stable Across CI Runs +## Keep Tracking Stable Across CI Runs Vite Task's [automatic tracking](/guide/automatic-tracking) records file reads, missing-file probes, and directory listings. In CI, a command can read files that describe the dependency install or tool state rather than source behavior. Those reads can change between runs and cause misses after a successful GitHub cache restore. Treat these cases by root cause: -- **Dependency install metadata.** Package managers and build tools can read install metadata to resolve packages, discover workspace layout, or configure file-system access. Track dependency identity with committed package manifests and lockfiles. For `vp build`, keep automatic tracking and add the lockfile as an input. Use explicit `input` globs only for commands with a small input set you can name. +- **Dependency install metadata.** Package managers and build tools can read install metadata to resolve packages, discover workspace layout, or configure file-system access. Track dependency identity with committed package manifests and lockfiles. For `vp build`, keep automatic tracking and add the lockfile as an input. Use explicit `input` globs only for commands with a small input set you can name. If that command writes files, review `output` in the same task config. - **Tool-owned incremental state.** Tools such as TypeScript can write incremental state into a directory they also scan. A fresh checkout may lack that file, so the next run can miss because the directory listing changed. Move that state into a generated cache directory or use explicit task inputs. For TypeScript, set `--tsBuildInfoFile` to a generated cache location instead of writing `*.tsbuildinfo` next to source files. -- **Task outputs.** If a task output also appears in the input fingerprint, deleting the output causes a miss instead of an output restore. Keep generated files out of `input`, then let Vite Task restore tracked outputs. +- **Task outputs.** If a task output also appears in the input fingerprint, deleting the output causes a miss instead of an output restore. Keep generated files out of `input`, then use `output` to choose which files Vite Task restores. - **Absolute arguments.** Vite Task stores command arguments in the fingerprint. If a command receives a different absolute checkout path between runs, it can miss with `args changed`. GitHub-hosted runners check out a repository under a stable path unless you override the checkout path. On self-hosted runners, keep the working directory stable or avoid absolute arguments. ## Choose A Cache Key From 574ccf91264af3719b19ebf547179d808bfdae85 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:17:10 +0800 Subject: [PATCH 10/46] docs: simplify automatic tracking wording --- docs/config/run.md | 4 ++-- docs/guide/cache.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/config/run.md b/docs/config/run.md index 857f277922..8ab73c1d51 100644 --- a/docs/config/run.md +++ b/docs/config/run.md @@ -230,7 +230,7 @@ Vite Task passes a set of common environment variables to all tasks: - **Type:** `Array` - **Default:** `[{ auto: true }]` (auto-inferred) -Vite Task automatically detects which files a command uses. See [Automatic Tracking](/guide/automatic-tracking) for the two tracking tiers and when to add manual config. The `input` option explicitly includes or excludes files from the cache fingerprint. Pair it with [`output`](#output) when a task writes files that Vite Task should restore. +Vite Task automatically detects which files a command uses. See [Automatic Tracking](/guide/automatic-tracking) for the details and when to add manual config. **Exclude files** from automatic tracking: @@ -294,7 +294,7 @@ String glob patterns are resolved relative to the package directory by default. - **Type:** `Array` - **Default:** automatic write tracking -Files Vite Task archives after a successful run and restores on a cache hit. Pair `output` with [`input`](#input) when a task writes files that it also reads, so generated files do not invalidate the cache entry Vite Task can restore. +Files Vite Task archives after a successful run and restores on a cache hit. If you omit `output`, Vite Task tracks files that the task writes and restores those files on cache hits. Use explicit output entries when you need to override the tracked files. diff --git a/docs/guide/cache.md b/docs/guide/cache.md index 469ed87802..01bb2bad41 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -45,7 +45,7 @@ The [`run.cache`](/config/run#run-cache) option in your root `vite.config.ts` co ## Automatic Tracking -Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn what each task needs for caching, so most tasks do not need manual tracking rules. Automatic tracking has two tiers: +Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn what each task needs for caching so you don't have to configure it manually. Automatic tracking has two tiers: - **File system tracking:** Vite Task records file reads, missing-file probes, directory listings, and written output files for every task with cache enabled. - **Cooperative tracking:** cache-reporting tools can report metadata that file system tracking cannot infer. Vite+ supports this for `vp build` today. From 607125137d8474000c97f30828d7498de590d7b2 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:27:24 +0800 Subject: [PATCH 11/46] docs: clarify automatic tracking cache behavior --- docs/guide/automatic-tracking.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index e7258ccb1d..712d3b9f82 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -1,6 +1,6 @@ # Automatic Tracking -Automatic tracking is how Vite Task learns whether a cached task can be reused. When you run a cached command through `vp run`, Vite Task records the files, outputs, and cache-reporting metadata that affect the result. On the next run, Vite Task compares that record with the current command and replays the task only when the fingerprint still matches. +Automatic tracking is how Vite Task learns what to cache for a task without explicit configurations. When you run a cache-enabled task, Vite Task observes the task's execution and records what files were read and written, as well as any metadata reported by the task. On the next run, Vite Task decides whether the cache misses or hits based on the recorded fingerprint. Use this page when you need to understand why a task hits or misses the cache, or when you need to decide whether to add `input`, `output`, `env`, or `untrackedEnv` config. @@ -8,16 +8,16 @@ Use this page when you need to understand why a task hits or misses the cache, o Automatic tracking has two tiers: -| Tier | Applies to | Records | -| -------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| File system tracking | All cached tasks run through `vp run` | Files read by the command, missing-file probes, directory listings, and written output files | -| Cooperative tracking | Cache-reporting tools | Metadata reported by the tool, such as environment variables and tool-owned paths that should not affect the task result | +| Tier | Applies to | Records | +| -------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| File system tracking | All tasks with cache enabled | Files read by the command, missing-file probes, directory listings, and written output files | +| Cooperative tracking | Cache-reporting tools | Metadata reported by the tool, such as environment variables and tool-managed cache paths that should not be considered as inputs or outputs (e.g. `node_modules/.vite-temp`) | Vite Task starts with file system tracking for any command. A cache-reporting tool can add information that only the tool knows while it runs. ## File System Tracking -File system tracking applies to every cached task run through `vp run`. If you omit [`input`](/config/run#input), Vite Task tracks the files a command reads while it runs: +File system tracking applies to every task to be cached. If you omit [`input`](/config/run#input), Vite Task tracks the files a command reads while it runs: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; From 77a87bd4f1890a94cee344d7196cef58e233e551 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:28:17 +0800 Subject: [PATCH 12/46] docs: add file tracking limitations --- docs/guide/automatic-tracking.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 712d3b9f82..30b1b86137 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -37,6 +37,14 @@ For this task, Vite Task records source files, config files, missing files the c File system tracking also tracks outputs. If you omit [`output`](/config/run#output), Vite Task archives files the command writes after a successful run and restores them on a cache hit. +### Limitations + +File system tracking records what the process touches. It cannot always tell which paths are stable inputs, generated outputs, or tool-managed state. + +Use [Override Inputs And Outputs](#override-inputs-and-outputs) when file access gives the wrong task boundary, such as when a task reads generated files, scans directories with unrelated files, or needs an extra dependency file in the fingerprint. + +Use [Cooperative Tracking](#cooperative-tracking) when the tool knows cache facts that file access does not expose, such as environment variables that affect the result or tool-managed cache paths that should not become inputs or outputs. + ### Override Inputs And Outputs Pair input and output overrides when a task writes files. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. From d2ed54541622709cf8083a95522a5db264d701df Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:30:12 +0800 Subject: [PATCH 13/46] docs: mention env read tracking limit --- docs/guide/automatic-tracking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 30b1b86137..7b1df90656 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -39,11 +39,11 @@ File system tracking also tracks outputs. If you omit [`output`](/config/run#out ### Limitations -File system tracking records what the process touches. It cannot always tell which paths are stable inputs, generated outputs, or tool-managed state. +File system tracking records file access, not every value a process reads. It cannot correctly track environment variable reads, and it cannot always tell which paths are stable inputs, generated outputs, or tool-managed state. Use [Override Inputs And Outputs](#override-inputs-and-outputs) when file access gives the wrong task boundary, such as when a task reads generated files, scans directories with unrelated files, or needs an extra dependency file in the fingerprint. -Use [Cooperative Tracking](#cooperative-tracking) when the tool knows cache facts that file access does not expose, such as environment variables that affect the result or tool-managed cache paths that should not become inputs or outputs. +Use [`env`](/config/run#env) when an environment variable changes a non-reporting command's result. Use [Cooperative Tracking](#cooperative-tracking) when the tool knows cache facts that file access does not expose, such as environment variables that affect the result or tool-managed cache paths that should not become inputs or outputs. ### Override Inputs And Outputs From 802248e15818466eaaa6aa422436e3eac3805068 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:31:20 +0800 Subject: [PATCH 14/46] docs: clarify automatic tracking limits --- docs/guide/automatic-tracking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 7b1df90656..9b4646603a 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -41,7 +41,7 @@ File system tracking also tracks outputs. If you omit [`output`](/config/run#out File system tracking records file access, not every value a process reads. It cannot correctly track environment variable reads, and it cannot always tell which paths are stable inputs, generated outputs, or tool-managed state. -Use [Override Inputs And Outputs](#override-inputs-and-outputs) when file access gives the wrong task boundary, such as when a task reads generated files, scans directories with unrelated files, or needs an extra dependency file in the fingerprint. +Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic file tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. Common cases include generated files, directory scans with unrelated files, and extra dependency files such as lockfiles. Use [`env`](/config/run#env) when an environment variable changes a non-reporting command's result. Use [Cooperative Tracking](#cooperative-tracking) when the tool knows cache facts that file access does not expose, such as environment variables that affect the result or tool-managed cache paths that should not become inputs or outputs. From 0e1077824a4de0ff93327403f130085a9c2c25bb Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:33:34 +0800 Subject: [PATCH 15/46] docs: clarify cooperative tracking support --- docs/guide/automatic-tracking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 9b4646603a..1343fa5d1c 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -41,9 +41,9 @@ File system tracking also tracks outputs. If you omit [`output`](/config/run#out File system tracking records file access, not every value a process reads. It cannot correctly track environment variable reads, and it cannot always tell which paths are stable inputs, generated outputs, or tool-managed state. -Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic file tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. Common cases include generated files, directory scans with unrelated files, and extra dependency files such as lockfiles. +Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic file tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. Common cases include generated files and directory scans with unrelated files. -Use [`env`](/config/run#env) when an environment variable changes a non-reporting command's result. Use [Cooperative Tracking](#cooperative-tracking) when the tool knows cache facts that file access does not expose, such as environment variables that affect the result or tool-managed cache paths that should not become inputs or outputs. +Use [`env`](/config/run#env) when an environment variable changes a non-reporting command's result. Supported tools provide [Cooperative Tracking](#cooperative-tracking) metadata automatically, such as environment variables that affect the result or tool-managed cache paths that should not become inputs or outputs. ### Override Inputs And Outputs From 968192359e273a00423184e1ef6f3625d7fa3cba Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:36:27 +0800 Subject: [PATCH 16/46] docs: clarify vp build cooperative tracking --- docs/guide/automatic-tracking.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 1343fa5d1c..40d360df7e 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -43,7 +43,9 @@ File system tracking records file access, not every value a process reads. It ca Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic file tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. Common cases include generated files and directory scans with unrelated files. -Use [`env`](/config/run#env) when an environment variable changes a non-reporting command's result. Supported tools provide [Cooperative Tracking](#cooperative-tracking) metadata automatically, such as environment variables that affect the result or tool-managed cache paths that should not become inputs or outputs. +Use [`env`](/config/run#env) when an environment variable changes a command's result. + +For `vp build`, Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including Vite environment variables and tool-managed cache paths that should not become inputs or outputs. ### Override Inputs And Outputs From 61539bec262b924eeba4332101af63cfe3d75b03 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:39:13 +0800 Subject: [PATCH 17/46] docs: clarify vp build manual tracking needs --- docs/guide/automatic-tracking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 40d360df7e..7f05dbc628 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -45,7 +45,7 @@ Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic f Use [`env`](/config/run#env) when an environment variable changes a command's result. -For `vp build`, Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including Vite environment variables and tool-managed cache paths that should not become inputs or outputs. +For `vp build`, Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env` entries for Vite's reported build metadata. ### Override Inputs And Outputs From 83788db5d986916da37640fc933eda7370fc907b Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:42:08 +0800 Subject: [PATCH 18/46] docs: show simple vp build tracking config --- docs/guide/automatic-tracking.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 7f05dbc628..c76481c7ab 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -45,7 +45,13 @@ Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic f Use [`env`](/config/run#env) when an environment variable changes a command's result. -For `vp build`, Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env` entries for Vite's reported build metadata. +For `vp build`, Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env` entries for that build metadata: + +```ts [vite.config.ts] +tasks: { + build: 'vp build', +} +``` ### Override Inputs And Outputs From 9c25130103fea8ac86c650deffe650169444434d Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:43:35 +0800 Subject: [PATCH 19/46] docs: refine automatic tracking limitations --- docs/guide/automatic-tracking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index c76481c7ab..751e6d08c7 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -45,7 +45,7 @@ Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic f Use [`env`](/config/run#env) when an environment variable changes a command's result. -For `vp build`, Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env` entries for that build metadata: +These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env` entries for that build metadata: ```ts [vite.config.ts] tasks: { @@ -55,7 +55,7 @@ tasks: { ### Override Inputs And Outputs -Pair input and output overrides when a task writes files. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. +Input and output overrides use the same rules and can be set independently. `{ auto: true }` keeps automatic tracking, string globs select paths, and `!` globs exclude paths. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. ```ts [vite.config.ts] tasks: { From a7c2870b1293b3b4e58cc2fd7dcc52163abea6fb Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:44:52 +0800 Subject: [PATCH 20/46] docs: simplify vp build tracking note --- docs/guide/automatic-tracking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 751e6d08c7..cfacb7f38b 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -45,7 +45,7 @@ Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic f Use [`env`](/config/run#env) when an environment variable changes a command's result. -These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env` entries for that build metadata: +These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env`: ```ts [vite.config.ts] tasks: { From d7c81812053f4ad4a5e5362f7e40062cd384eee3 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:52:21 +0800 Subject: [PATCH 21/46] docs: clarify input and output overrides --- docs/guide/automatic-tracking.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index cfacb7f38b..4fb04acf23 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -55,7 +55,10 @@ tasks: { ### Override Inputs And Outputs -Input and output overrides use the same rules and can be set independently. `{ auto: true }` keeps automatic tracking, string globs select paths, and `!` globs exclude paths. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. +- [`input`](/config/run#input) controls what invalidates the cache. +- [`output`](/config/run#output) controls which files Vite Task restores on a cache hit. + +Both options accept the same kinds of entries and can be configured separately. Omit an option to keep automatic tracking for it. Add `{ auto: true }` to keep automatic tracking while adding glob rules. Use string globs to include paths and `!` globs to exclude paths. Use `[]` to replace automatic tracking with an empty list. ```ts [vite.config.ts] tasks: { @@ -67,7 +70,7 @@ tasks: { } ``` -Use explicit `input` globs only when the command has a small, stable input set you can name. Commands that do not write outputs do not need `output`: +Use explicit `input` globs only when you can name the command's full, stable input set. This lint task overrides inputs only, so output tracking stays automatic: ```ts [vite.config.ts] tasks: { @@ -78,7 +81,7 @@ tasks: { } ``` -Use explicit `output` globs when you want to narrow or extend the files Vite Task restores. If the command also reads its output directory, exclude that directory from `input`: +Use explicit `output` globs when you want to narrow or extend the files Vite Task restores: ```ts [vite.config.ts] tasks: { @@ -90,7 +93,7 @@ tasks: { } ``` -Set `input: []` to disable file tracking for a task. Set `output: []` to disable output restoration. The task can still use cache entries based on command arguments and tracked environment variables. +Set `input: []` when no files should affect the cache key. Set `output: []` when no files should be restored on a cache hit. ## Cooperative Tracking From 5cffa454550c6cade7ceb70c38cb23d04f986bf0 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:54:17 +0800 Subject: [PATCH 22/46] docs: rework cooperative tracking section --- docs/guide/automatic-tracking.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 4fb04acf23..a85233d4b6 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -97,15 +97,17 @@ Set `input: []` when no files should affect the cache key. Set `output: []` when ## Cooperative Tracking -Some tools know cache dependencies that file system tracking cannot infer from the outside. A cache-reporting tool can cooperate with Vite Task while it runs. Vite Task still observes file reads and writes. It uses the report to refine the cache fingerprint. +File system tracking sees access. It cannot always see intent. -Vite+ supports cooperative tracking for `vp build` today. When a task runs `vp build`, Vite reports build cache metadata to Vite Task. For a standard Vite build, you do not need to add these entries yourself: +`vp build` knows more about a Vite build than Vite Task can infer from file access. When a cached task runs `vp build`, Vite reports that metadata to Vite Task. Vite Task merges the report with file system tracking to build a more accurate cache fingerprint. + +For a standard Vite build, you do not need to add these entries yourself: - `env: ['VITE_*']` or `env: ['NODE_ENV']` - `output: ['dist/**']` -- explicit input globs that replace file system tracking +- input or output rules for tool-managed temporary paths -Define the build as a `vp run` task: +The user still defines what to run: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; @@ -119,7 +121,7 @@ export default defineConfig({ }); ``` -Then run it with: +Run the task through Vite Task: ```bash vp run build @@ -127,7 +129,9 @@ vp run build Direct `vp build` runs a build, but it does not use the Vite Task cache. Use `vp run build` when you want task caching. -Vite+ will extend cooperative tracking to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). +Manual config still wins. Add `input`, `output`, or `env` when your project has behavior that Vite cannot know. + +Vite+ supports cooperative tracking for `vp build` today. It will extend this support to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). ## When To Add Manual Config From 50111200e3372fb61f1a4e1ed3c7947ded63905d Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:57:44 +0800 Subject: [PATCH 23/46] docs: refine cooperative tracking guidance --- docs/guide/automatic-tracking.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index a85233d4b6..83fa182296 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -99,15 +99,15 @@ Set `input: []` when no files should affect the cache key. Set `output: []` when File system tracking sees access. It cannot always see intent. -`vp build` knows more about a Vite build than Vite Task can infer from file access. When a cached task runs `vp build`, Vite reports that metadata to Vite Task. Vite Task merges the report with file system tracking to build a more accurate cache fingerprint. +`vp build` knows more about a Vite build than Vite Task can infer from file access. When `vp build` runs with cache enabled, Vite reports that metadata to Vite Task. Vite Task merges the report with file system tracking to build a more accurate cache fingerprint. For a standard Vite build, you do not need to add these entries yourself: - `env: ['VITE_*']` or `env: ['NODE_ENV']` - `output: ['dist/**']` -- input or output rules for tool-managed temporary paths +- input or output rules for temporary paths like `node_modules/.vite-temp` -The user still defines what to run: +Define the task with `vp build`: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; @@ -121,14 +121,6 @@ export default defineConfig({ }); ``` -Run the task through Vite Task: - -```bash -vp run build -``` - -Direct `vp build` runs a build, but it does not use the Vite Task cache. Use `vp run build` when you want task caching. - Manual config still wins. Add `input`, `output`, or `env` when your project has behavior that Vite cannot know. Vite+ supports cooperative tracking for `vp build` today. It will extend this support to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). From 2232776b818a5d2df74caad179b5e3828ac0f44a Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 01:59:28 +0800 Subject: [PATCH 24/46] docs: refine vp build task wording --- docs/guide/automatic-tracking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 83fa182296..8854f96619 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -107,7 +107,7 @@ For a standard Vite build, you do not need to add these entries yourself: - `output: ['dist/**']` - input or output rules for temporary paths like `node_modules/.vite-temp` -Define the task with `vp build`: +You only need to define the task with `vp build`: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; From a2ba2a1bafe391b2967a13cc9d905dd344db1b98 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:02:46 +0800 Subject: [PATCH 25/46] docs: remove cache miss section from tracking guide --- docs/guide/automatic-tracking.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 8854f96619..678d809e32 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -151,15 +151,3 @@ tasks: { ``` This task keeps file system tracking, lets Vite report build metadata, adds the lockfile to the fingerprint, excludes restored output files from inputs, and restores only `dist/**` on a cache hit. - -## Common Cache Miss Causes - -Vite Task chooses a cache miss when tracked data changed between runs. In CI, these data sources often explain misses after a restored cache: - -- **Dependency install metadata:** add committed package manifests and lockfiles as inputs. For `vp build`, keep automatic tracking and add the lockfile. -- **Tool-owned incremental state:** move incremental files into a generated cache directory or exclude them from file system-tracked inputs. -- **Generated outputs:** exclude output directories from `input`, then configure `output` so Vite Task can restore them. -- **Broad directory scans:** use explicit `input` globs when a command scans directories that contain unrelated files. If the command writes files, review `output` in the same task config. -- **Environment variables:** add `env` for variables that change a non-reporting command's result. Leave standard Vite build env vars out of `env` because `vp build` reports them. - -For GitHub Actions cache reuse, see [GitHub Actions Cache](/guide/github-actions-cache). That guide explains how to restore `node_modules/.vite/task-cache` between CI runs after your task hits locally. From 1994686b34eb53656aaacd8686ea60f867224aa3 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:08:35 +0800 Subject: [PATCH 26/46] docs: simplify manual tracking config table --- docs/guide/automatic-tracking.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 678d809e32..8d97c95752 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -129,14 +129,12 @@ Vite+ supports cooperative tracking for `vp build` today. It will extend this su Add config when your project has behavior the command or tool cannot know. -| Goal | Config | -| -------------------------------------------------------- | ---------------------------------------------- | -| Keep file system tracking and add CI dependency identity | `input: [{ auto: true }, 'pnpm-lock.yaml']` | -| Exclude generated output from the input fingerprint | `input: [{ auto: true }, '!dist', '!dist/**']` | -| Replace file system tracking for a small input set | `input: ['src/**', 'package.json']` | -| Narrow output restoration | `output: ['dist/**']` | -| Track an env var used by a non-reporting command | `env: ['NODE_ENV']` | -| Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` | +| Case | Config | +| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist', '!dist/**']` | +| Exclude a temporary generated file from input and output tracking | `input: [{ auto: true }, '!.tmp/config.mjs']`
`output: [{ auto: true }, '!.tmp/config.mjs']` | +| Track an env var used by a non-cooperative command | `env: ['NODE_ENV']` | +| Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` | For CI builds, keep automatic tracking for `vp build` and add only the extra project facts CI needs: From 9e9222926292b5dbd21edd66b733853a5e89446f Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:10:30 +0800 Subject: [PATCH 27/46] docs: add file tracking disable case --- docs/guide/automatic-tracking.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 8d97c95752..502f611808 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -133,6 +133,7 @@ Add config when your project has behavior the command or tool cannot know. | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Exclude an output directory from inputs | `input: [{ auto: true }, '!dist', '!dist/**']` | | Exclude a temporary generated file from input and output tracking | `input: [{ auto: true }, '!.tmp/config.mjs']`
`output: [{ auto: true }, '!.tmp/config.mjs']` | +| Disable file tracking when it changes command behavior | `input: []` | | Track an env var used by a non-cooperative command | `env: ['NODE_ENV']` | | Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` | From 274894432506acc5b34d3e20b1b750936a245cd9 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:13:37 +0800 Subject: [PATCH 28/46] docs: format automatic tracking records --- docs/guide/automatic-tracking.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 502f611808..60480044a4 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -8,10 +8,10 @@ Use this page when you need to understand why a task hits or misses the cache, o Automatic tracking has two tiers: -| Tier | Applies to | Records | -| -------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| File system tracking | All tasks with cache enabled | Files read by the command, missing-file probes, directory listings, and written output files | -| Cooperative tracking | Cache-reporting tools | Metadata reported by the tool, such as environment variables and tool-managed cache paths that should not be considered as inputs or outputs (e.g. `node_modules/.vite-temp`) | +| Tier | Applies to | Records | +| -------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| File system tracking | All tasks with cache enabled |
  • Files read by the command
  • Missing-file probes
  • Directory listings
  • Written output files
| +| Cooperative tracking | Cache-reporting tools (`vp build` today) |
  • Environment variables reported by the tool
  • Tool-managed paths that should not be inputs or outputs, such as `node_modules/.vite-temp`
| Vite Task starts with file system tracking for any command. A cache-reporting tool can add information that only the tool knows while it runs. From 8161fe67c1f8f77350dbcb945d82e87edf488e12 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:30:52 +0800 Subject: [PATCH 29/46] docs: revise automatic tracking guide --- docs/guide/automatic-tracking.md | 83 ++++++++++++-------------------- 1 file changed, 32 insertions(+), 51 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 60480044a4..73774ef00a 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -1,6 +1,8 @@ # Automatic Tracking -Automatic tracking is how Vite Task learns what to cache for a task without explicit configurations. When you run a cache-enabled task, Vite Task observes the task's execution and records what files were read and written, as well as any metadata reported by the task. On the next run, Vite Task decides whether the cache misses or hits based on the recorded fingerprint. +Automatic tracking is how Vite Task learns what to cache for a task without explicit configurations. + +When you run a cache-enabled task, Vite Task observes the task's execution and records what files were read and written, as well as any metadata reported by the task. On the next run, Vite Task decides whether the cache misses or hits based on the recorded fingerprint. Use this page when you need to understand why a task hits or misses the cache, or when you need to decide whether to add `input`, `output`, `env`, or `untrackedEnv` config. @@ -39,61 +41,54 @@ File system tracking also tracks outputs. If you omit [`output`](/config/run#out ### Limitations -File system tracking records file access, not every value a process reads. It cannot correctly track environment variable reads, and it cannot always tell which paths are stable inputs, generated outputs, or tool-managed state. +Vite Task cannot track environment variable reads, and it cannot always tell which tracked paths are stable inputs, generated outputs, or tool-managed cache (which should not be considered as inputs or outputs). -Use [Override Inputs And Outputs](#override-inputs-and-outputs) when automatic file tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. Common cases include generated files and directory scans with unrelated files. +Use [Override Inputs And Outputs](#override-inputs-and-outputs) when file system tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. -Use [`env`](/config/run#env) when an environment variable changes a command's result. +Use [`env`](/config/run#env) when an environment variable needs to be fingerprinted in cache and passed to the command. Use [`untrackedEnv`](/config/run#untrackedenv) when an environment variable needs to be passed to the command but should not affect the cache. -These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and tool-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env`: - -```ts [vite.config.ts] -tasks: { - build: 'vp build', -} -``` +These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and Vite-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env`. ### Override Inputs And Outputs -- [`input`](/config/run#input) controls what invalidates the cache. -- [`output`](/config/run#output) controls which files Vite Task restores on a cache hit. +[`input`](/config/run#input) controls what invalidates the cache. +[`output`](/config/run#output) controls which files Vite Task restores on a cache hit. -Both options accept the same kinds of entries and can be configured separately. Omit an option to keep automatic tracking for it. Add `{ auto: true }` to keep automatic tracking while adding glob rules. Use string globs to include paths and `!` globs to exclude paths. Use `[]` to replace automatic tracking with an empty list. +They shared the same syntax and can be configured separately. + +- Omit to keep automatic tracking for it. +- Add `{ auto: true }` to keep automatic tracking along with globs. +- Use string globs to include paths +- `!` globs to exclude paths. +- Use `[]` to replace automatic tracking with an empty list. ```ts [vite.config.ts] tasks: { build: { command: 'node build.mjs', - input: [{ auto: true }, '!dist', '!dist/**'], + + // Keep automatic input tracking, but exclude `dist` from inputs + input: [{ auto: true }, '!dist/**'], + // Disable automatic output tracking and restore only `dist/**` on a cache hit output: ['dist/**'], }, } ``` -Use explicit `input` globs only when you can name the command's full, stable input set. This lint task overrides inputs only, so output tracking stays automatic: +Use explicit `input`/`output` globs only when you know the command's full input/output set: ```ts [vite.config.ts] tasks: { lint: { command: 'vp lint', - input: ['package.json', 'pnpm-lock.yaml', 'src/**', 'tsconfig*.json'], - }, -} -``` - -Use explicit `output` globs when you want to narrow or extend the files Vite Task restores: - -```ts [vite.config.ts] -tasks: { - build: { - command: 'node build.mjs', - input: [{ auto: true }, '!dist', '!dist/**'], - output: ['dist/**'], + // Disable automatic input tracking and fingerprint only these files + input: ['src/**', 'vite.config.ts'], + // Keep automatic output tracking because `output` is not specified }, } ``` -Set `input: []` when no files should affect the cache key. Set `output: []` when no files should be restored on a cache hit. +Set `input: []` when no files should affect the cache fingerprint. Set `output: []` when no files should be restored on a cache hit. ## Cooperative Tracking @@ -101,11 +96,11 @@ File system tracking sees access. It cannot always see intent. `vp build` knows more about a Vite build than Vite Task can infer from file access. When `vp build` runs with cache enabled, Vite reports that metadata to Vite Task. Vite Task merges the report with file system tracking to build a more accurate cache fingerprint. -For a standard Vite build, you do not need to add these entries yourself: +For a standard Vite build, you do not need to add these entries yourself because Vite reports them automatically at runtime: - `env: ['VITE_*']` or `env: ['NODE_ENV']` - `output: ['dist/**']` -- input or output rules for temporary paths like `node_modules/.vite-temp` +- input or output exclusions for temporary paths like `node_modules/.vite-temp` You only need to define the task with `vp build`: @@ -121,7 +116,7 @@ export default defineConfig({ }); ``` -Manual config still wins. Add `input`, `output`, or `env` when your project has behavior that Vite cannot know. +Manual config still wins. Add `input`, `output`, `env` or `untrackedEnv` when even cooperative tracking misses something. Vite+ supports cooperative tracking for `vp build` today. It will extend this support to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). @@ -129,24 +124,10 @@ Vite+ supports cooperative tracking for `vp build` today. It will extend this su Add config when your project has behavior the command or tool cannot know. -| Case | Config | +| Case | Example | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist', '!dist/**']` | +| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist']` | | Exclude a temporary generated file from input and output tracking | `input: [{ auto: true }, '!.tmp/config.mjs']`
`output: [{ auto: true }, '!.tmp/config.mjs']` | -| Disable file tracking when it changes command behavior | `input: []` | -| Track an env var used by a non-cooperative command | `env: ['NODE_ENV']` | +| Disable file tracking when it makes your task misbehave | `input: ["src/**"], output: ["dist/**"]` | +| Track and pass an env var | `env: ['NODE_ENV']` | | Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` | - -For CI builds, keep automatic tracking for `vp build` and add only the extra project facts CI needs: - -```ts [vite.config.ts] -tasks: { - 'ci-build': { - command: 'vp build', - input: [{ auto: true }, 'pnpm-lock.yaml', '!dist', '!dist/**'], - output: ['dist/**'], - }, -} -``` - -This task keeps file system tracking, lets Vite report build metadata, adds the lockfile to the fingerprint, excludes restored output files from inputs, and restores only `dist/**` on a cache hit. From 2e97080199695f8ad54875006206857a4ee2fc3c Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:32:36 +0800 Subject: [PATCH 30/46] docs: polish automatic tracking guidance --- docs/guide/automatic-tracking.md | 34 ++++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 73774ef00a..234a930a67 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -41,11 +41,11 @@ File system tracking also tracks outputs. If you omit [`output`](/config/run#out ### Limitations -Vite Task cannot track environment variable reads, and it cannot always tell which tracked paths are stable inputs, generated outputs, or tool-managed cache (which should not be considered as inputs or outputs). +Vite Task cannot track environment variable reads, and it cannot always tell which tracked paths are stable inputs, generated outputs, or tool-managed cache paths. Use [Override Inputs And Outputs](#override-inputs-and-outputs) when file system tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. -Use [`env`](/config/run#env) when an environment variable needs to be fingerprinted in cache and passed to the command. Use [`untrackedEnv`](/config/run#untrackedenv) when an environment variable needs to be passed to the command but should not affect the cache. +Use [`env`](/config/run#env) when a command needs an environment variable and the value should affect the cache. Use [`untrackedEnv`](/config/run#untrackedenv) when a command needs an environment variable but the value should not affect the cache. These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and Vite-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env`. @@ -54,12 +54,12 @@ These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking [`input`](/config/run#input) controls what invalidates the cache. [`output`](/config/run#output) controls which files Vite Task restores on a cache hit. -They shared the same syntax and can be configured separately. - -- Omit to keep automatic tracking for it. -- Add `{ auto: true }` to keep automatic tracking along with globs. -- Use string globs to include paths -- `!` globs to exclude paths. +Both options use the same syntax and can be configured separately. + +- Omit the option to keep automatic tracking. +- Add `{ auto: true }` to keep automatic tracking while adding glob rules. +- Use string globs to include paths. +- Use `!` globs to exclude paths. - Use `[]` to replace automatic tracking with an empty list. ```ts [vite.config.ts] @@ -67,23 +67,23 @@ tasks: { build: { command: 'node build.mjs', - // Keep automatic input tracking, but exclude `dist` from inputs - input: [{ auto: true }, '!dist/**'], - // Disable automatic output tracking and restore only `dist/**` on a cache hit + // Keep automatic input tracking, but exclude `dist` from inputs. + input: [{ auto: true }, '!dist', '!dist/**'], + + // Disable automatic output tracking and restore only `dist/**` on a cache hit. output: ['dist/**'], }, } ``` -Use explicit `input`/`output` globs only when you know the command's full input/output set: +Use explicit `input` globs only when you know the command's full input set. This lint task overrides inputs only, so output tracking stays automatic: ```ts [vite.config.ts] tasks: { lint: { command: 'vp lint', - // Disable automatic input tracking and fingerprint only these files + // Disable automatic input tracking and fingerprint only these files. input: ['src/**', 'vite.config.ts'], - // Keep automatic output tracking because `output` is not specified }, } ``` @@ -116,7 +116,7 @@ export default defineConfig({ }); ``` -Manual config still wins. Add `input`, `output`, `env` or `untrackedEnv` when even cooperative tracking misses something. +Manual config still wins. Add `input`, `output`, `env`, or `untrackedEnv` when your project has behavior that Vite cannot report. Vite+ supports cooperative tracking for `vp build` today. It will extend this support to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). @@ -126,8 +126,8 @@ Add config when your project has behavior the command or tool cannot know. | Case | Example | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist']` | +| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist', '!dist/**']` | | Exclude a temporary generated file from input and output tracking | `input: [{ auto: true }, '!.tmp/config.mjs']`
`output: [{ auto: true }, '!.tmp/config.mjs']` | -| Disable file tracking when it makes your task misbehave | `input: ["src/**"], output: ["dist/**"]` | +| Avoid automatic file tracking for a task | `input: ['src/**']`
`output: ['dist/**']` | | Track and pass an env var | `env: ['NODE_ENV']` | | Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` | From 5b363e180019c37e13d5f7a66db82b2f43f20d42 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:36:26 +0800 Subject: [PATCH 31/46] docs: tighten automatic tracking examples --- docs/guide/automatic-tracking.md | 6 +++--- docs/guide/cache.md | 2 +- docs/guide/github-actions-cache.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index 234a930a67..df1a32e874 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -41,7 +41,7 @@ File system tracking also tracks outputs. If you omit [`output`](/config/run#out ### Limitations -Vite Task cannot track environment variable reads, and it cannot always tell which tracked paths are stable inputs, generated outputs, or tool-managed cache paths. +Vite Task cannot track environment variable reads, and it cannot always tell which tracked paths are stable inputs, generated outputs, or tool-managed cache paths that should not become inputs or outputs. Use [Override Inputs And Outputs](#override-inputs-and-outputs) when file system tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs. @@ -68,7 +68,7 @@ tasks: { command: 'node build.mjs', // Keep automatic input tracking, but exclude `dist` from inputs. - input: [{ auto: true }, '!dist', '!dist/**'], + input: [{ auto: true }, '!dist/**'], // Disable automatic output tracking and restore only `dist/**` on a cache hit. output: ['dist/**'], @@ -126,7 +126,7 @@ Add config when your project has behavior the command or tool cannot know. | Case | Example | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist', '!dist/**']` | +| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist/**']` | | Exclude a temporary generated file from input and output tracking | `input: [{ auto: true }, '!.tmp/config.mjs']`
`output: [{ auto: true }, '!.tmp/config.mjs']` | | Avoid automatic file tracking for a task | `input: ['src/**']`
`output: ['dist/**']` | | Track and pass an env var | `env: ['NODE_ENV']` | diff --git a/docs/guide/cache.md b/docs/guide/cache.md index 01bb2bad41..455215eacb 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -56,7 +56,7 @@ Use [`input`](/config/run#input) and [`output`](/config/run#output) together whe tasks: { build: { command: 'node build.mjs', - input: [{ auto: true }, '!dist', '!dist/**'], + input: [{ auto: true }, '!dist/**'], output: ['dist/**'], }, } diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index 6d0d94a7b7..f42997f25d 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -40,7 +40,7 @@ export default defineConfig({ tasks: { 'ci-build': { command: 'vp build', - input: [{ auto: true }, 'pnpm-lock.yaml', '!dist', '!dist/**'], + input: [{ auto: true }, 'pnpm-lock.yaml', '!dist/**'], output: ['dist/**'], }, 'ci-lint': { From 7ae74eee424f46d55f133914a66c34585eb0aec0 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:42:36 +0800 Subject: [PATCH 32/46] docs: simplify GitHub Actions cache tasks --- docs/guide/github-actions-cache.md | 41 ++++++++++++------------------ 1 file changed, 16 insertions(+), 25 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index f42997f25d..7e05d63d06 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -9,7 +9,7 @@ Vite Task stores task results in `node_modules/.vite/task-cache` at the workspac GitHub Actions cache and Vite Task make separate decisions: 1. `actions/cache` restores and saves the cache directory based on the key in your workflow. -2. Vite Task checks the restored entries and replays only the tasks whose fingerprints still match. +2. Vite Task uses the restored cache directory and replays only the tasks whose fingerprints still match. This cache is separate from dependency caching. Keep using [`setup-vp` cache support](/guide/ci) for package installs, then restore the Vite Task cache after dependencies are installed. @@ -26,11 +26,11 @@ Fix local misses first. GitHub Actions cache can move Vite Task's local cache di ## 1. Define Cacheable CI Tasks -Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache; run `vp run build` or define a CI-specific task. +Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache. Define a task in your `vite.config.ts` for each command you want to cache in CI. -The example below uses [automatic tracking](/guide/automatic-tracking) for `vp build`. Vite Task tracks file reads, and Vite reports build metadata that file tracking cannot infer. A short explicit input list can miss files such as `public/**`, `.env*`, or framework config. The extra lockfile input ties the task fingerprint to dependency identity. +The example below uses [automatic tracking](/guide/automatic-tracking) for `vp build`. Vite Task tracks file reads, and Vite reports build metadata that file tracking cannot infer. Do not replace it with a short explicit input list, which can miss files such as `public/**`, `.env*`, or framework config. -The lint task uses explicit inputs because its CI input set is smaller. If you use npm, Yarn, or Bun, replace `pnpm-lock.yaml` with the lockfile your project commits. +The lint task uses explicit inputs because its CI input set is small and stable. ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; @@ -38,29 +38,25 @@ import { defineConfig } from 'vite-plus'; export default defineConfig({ run: { tasks: { - 'ci-build': { - command: 'vp build', - input: [{ auto: true }, 'pnpm-lock.yaml', '!dist/**'], - output: ['dist/**'], - }, - 'ci-lint': { + build: 'vp build', + lint: { command: 'vp lint', - input: ['package.json', 'pnpm-lock.yaml', 'src/**', 'tsconfig*.json', 'vite.config.ts'], + input: ['src/**', 'tsconfig*.json', 'vite.config.ts'], }, }, }, }); ``` -The build task sets `output: ['dist/**']` to narrow output restoration to `dist`. The `!dist` input exclusions keep generated output files from invalidating the same cache entry Vite Task can restore. If you omit `output`, Vite Task tracks files that the task writes and restores those files on cache hits. Use [`output`](/config/run#output) when you need to narrow, extend, or disable output restoration. +The build task needs no manual `input`, `output`, or `env` entries for a standard Vite build. The lint task overrides only `input`, so output tracking stays automatic. Run each task twice: ```bash -vp run ci-build -vp run ci-build # should print "cache hit" -vp run ci-lint -vp run ci-lint # should print "cache hit" +vp run build +vp run build # should print "cache hit" +vp run lint +vp run lint # should print "cache hit" ``` For other auto-tracked tasks that produce files, use the same output pattern: @@ -73,7 +69,7 @@ export default defineConfig({ tasks: { report: { command: 'node scripts/report.mjs', - input: [{ auto: true }, '!reports', '!reports/**'], + input: [{ auto: true }, '!reports/**'], output: ['reports/**'], }, }, @@ -119,8 +115,8 @@ jobs: restore-keys: | vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml', '**/package-lock.json', '**/yarn.lock', '**/bun.lock', '**/bun.lockb') }}- - - run: vp run ci-lint - - run: vp run ci-build + - run: vp run lint + - run: vp run build - name: Save Vite Task cache if: success() @@ -167,12 +163,7 @@ export default defineConfig({ build: { command: 'vp build', dependsOn: [{ task: 'build', from: 'dependencies' }], - input: [ - { auto: true }, - { pattern: 'pnpm-lock.yaml', base: 'workspace' }, - '!dist', - '!dist/**', - ], + input: [{ auto: true }, { pattern: 'pnpm-lock.yaml', base: 'workspace' }, '!dist/**'], output: ['dist/**'], }, }, From 504e6aeefb0dc0f57786a2ec5467d5e132df97bd Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:44:26 +0800 Subject: [PATCH 33/46] docs: simplify CI task cache setup --- docs/guide/github-actions-cache.md | 33 +++--------------------------- 1 file changed, 3 insertions(+), 30 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index 7e05d63d06..ea153bacaa 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -26,11 +26,7 @@ Fix local misses first. GitHub Actions cache can move Vite Task's local cache di ## 1. Define Cacheable CI Tasks -Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache. Define a task in your `vite.config.ts` for each command you want to cache in CI. - -The example below uses [automatic tracking](/guide/automatic-tracking) for `vp build`. Vite Task tracks file reads, and Vite reports build metadata that file tracking cannot infer. Do not replace it with a short explicit input list, which can miss files such as `public/**`, `.env*`, or framework config. - -The lint task uses explicit inputs because its CI input set is small and stable. +Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache. Define a task in `vite.config.ts` for each command you want to cache in CI: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; @@ -39,16 +35,13 @@ export default defineConfig({ run: { tasks: { build: 'vp build', - lint: { - command: 'vp lint', - input: ['src/**', 'tsconfig*.json', 'vite.config.ts'], - }, + lint: 'vp lint', }, }, }); ``` -The build task needs no manual `input`, `output`, or `env` entries for a standard Vite build. The lint task overrides only `input`, so output tracking stays automatic. +Keep tracking config in `vite.config.ts`. See [Automatic Tracking](/guide/automatic-tracking) and [`run.tasks`](/config/run#tasks) for `input`, `output`, `env`, and `untrackedEnv`. Run each task twice: @@ -59,26 +52,6 @@ vp run lint vp run lint # should print "cache hit" ``` -For other auto-tracked tasks that produce files, use the same output pattern: - -```ts [vite.config.ts] -import { defineConfig } from 'vite-plus'; - -export default defineConfig({ - run: { - tasks: { - report: { - command: 'node scripts/report.mjs', - input: [{ auto: true }, '!reports/**'], - output: ['reports/**'], - }, - }, - }, -}); -``` - -For a standard Vite build, you do not need to add `env: ['VITE_*']` or replace automatic tracking. Add explicit `input` entries only to track extra files such as lockfiles or to exclude generated outputs. Add explicit `output` entries only when you need to narrow, extend, or disable output restoration. - ## 2. Restore The Cache After Install Restore `node_modules/.vite/task-cache` after `vp install`, because package installation can recreate or modify `node_modules`. From 987d3822e4c68b40ad7ae914d008f230eb381dc6 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:46:19 +0800 Subject: [PATCH 34/46] docs: shorten tracking config reference --- docs/guide/github-actions-cache.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index ea153bacaa..d3afd735e3 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -41,7 +41,7 @@ export default defineConfig({ }); ``` -Keep tracking config in `vite.config.ts`. See [Automatic Tracking](/guide/automatic-tracking) and [`run.tasks`](/config/run#tasks) for `input`, `output`, `env`, and `untrackedEnv`. +Keep tracking config in `vite.config.ts`. See [Automatic Tracking](/guide/automatic-tracking) and [`run.tasks`](/config/run#tasks) for details. Run each task twice: From abb5809bb4b43da360d600ce8a52453277bbcbbd Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:47:54 +0800 Subject: [PATCH 35/46] docs: clarify local hit prerequisite --- docs/guide/github-actions-cache.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index d3afd735e3..f4de2018df 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -41,7 +41,7 @@ export default defineConfig({ }); ``` -Keep tracking config in `vite.config.ts`. See [Automatic Tracking](/guide/automatic-tracking) and [`run.tasks`](/config/run#tasks) for details. +This guide assumes each task already hits locally. If a task misses, fix its tracking config in `vite.config.ts` before adding the GitHub Actions cache steps. See [Automatic Tracking](/guide/automatic-tracking) and [`run.tasks`](/config/run#tasks). Run each task twice: From 75d1a77cc578f5db6c3ed12d4c1180a3ebaa2c2b Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:56:24 +0800 Subject: [PATCH 36/46] docs: simplify GitHub Actions cache guide --- docs/guide/github-actions-cache.md | 48 ++++++------------------------ 1 file changed, 9 insertions(+), 39 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index f4de2018df..2dd061b47c 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -84,9 +84,9 @@ jobs: uses: actions/cache/restore@v6 with: path: node_modules/.vite/task-cache - key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml', '**/package-lock.json', '**/yarn.lock', '**/bun.lock', '**/bun.lockb') }}-${{ github.run_id }}-${{ github.run_attempt }} + key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }} restore-keys: | - vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml', '**/package-lock.json', '**/yarn.lock', '**/bun.lock', '**/bun.lockb') }}- + vite-task-${{ runner.os }}-${{ runner.arch }}- - run: vp run lint - run: vp run build @@ -99,9 +99,11 @@ jobs: key: ${{ steps.vite-task-cache.outputs.cache-primary-key }} ``` -The primary key includes `github.run_id` and `github.run_attempt` so each successful run can save a new immutable cache entry. The restore prefix includes the lockfile hash, so a dependency change starts from a cold Vite Task cache instead of restoring entries from a different dependency graph. +The primary key includes `github.run_id` and `github.run_attempt` so each successful run can save a new immutable cache entry. The restore prefix lets GitHub restore the newest cache for the same operating system and architecture. Vite Task checks the restored entries before replaying a task. -Leave source files out of the GitHub Actions key. Vite Task fingerprints task inputs. If a source change updates the Actions key, GitHub can skip useful restores before Vite Task decides which tasks still hit. +Leave task inputs, including source files and lockfiles, out of the GitHub Actions key. Vite Task fingerprints them. If they change the Actions key, GitHub can skip useful restores before Vite Task decides which tasks still hit. + +For workspaces, restore the task cache from the workspace root. Then run the same workspace targets you use locally, such as `vp run -t @my/app#build`. Vite Task checks each restored entry before replaying it, including tasks from workspace dependencies. ## 3. Verify In The Logs @@ -117,37 +119,6 @@ vp run: cache hit, 1.10s saved. If GitHub restores a cache but Vite Task prints a cache miss, the Actions cache transport worked, but the task fingerprint changed. -## 4. Workspaces - -Cache reuse works with workspace task targets. Define cacheable tasks in the package that owns the target, then run the same `vp run` command in CI: - -```bash -vp run -t @my/app#build -``` - -For workspace builds, keep automatic tracking and add the workspace lockfile as a workspace-relative input: - -```ts [vite.config.ts] -import { defineConfig } from 'vite-plus'; - -export default defineConfig({ - run: { - tasks: { - build: { - command: 'vp build', - dependsOn: [{ task: 'build', from: 'dependencies' }], - input: [{ auto: true }, { pattern: 'pnpm-lock.yaml', base: 'workspace' }, '!dist/**'], - output: ['dist/**'], - }, - }, - }, -}); -``` - -The object-form `dependsOn` runs `build` in direct workspace dependency packages that define that task. Each dependency can pull in more tasks through its own `dependsOn` config. - -When the task cache is restored, Vite Task can replay hits for the target package and its workspace dependencies. In a transitive `core -> util -> app` experiment, restoring only `node_modules/.vite/task-cache` in a fresh checkout produced `3/3` cache hits and restored each package's `dist/**` output. - ## Keep Tracking Stable Across CI Runs Vite Task's [automatic tracking](/guide/automatic-tracking) records file reads, missing-file probes, and directory listings. In CI, a command can read files that describe the dependency install or tool state rather than source behavior. Those reads can change between runs and cause misses after a successful GitHub cache restore. @@ -164,9 +135,9 @@ Treat these cases by root cause: Use a rolling primary key plus a restore prefix: ```yaml [.github/workflows/ci.yml] -key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml') }}-${{ github.run_id }}-${{ github.run_attempt }} +key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }} restore-keys: | - vite-task-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pnpm-lock.yaml') }}- + vite-task-${{ runner.os }}-${{ runner.arch }}- ``` The exact key misses on each new run because the key contains `github.run_id` and `github.run_attempt`. GitHub then searches the restore prefix and restores the newest matching cache. Vite Task checks restored entries before replaying a task. @@ -174,10 +145,9 @@ The exact key misses on each new run because the key contains `github.run_id` an Include: - `runner.os` and `runner.arch`, because outputs and native tools can be platform-specific. -- Your lockfile hash, so GitHub restores caches from the same dependency graph. - A per-run value such as `github.run_id` and `github.run_attempt`, because GitHub cache entries are immutable. -You can add a broader restore prefix only if the task inputs include the package manifests and lockfiles that define dependency identity. The broader prefix can save a download on some projects, but it can also restore a cache that Vite Task rejects task by task. +If a dependency file affects a task result, track it in the task fingerprint rather than the GitHub Actions key. ## Limitations And Workarounds From 5d44d89e922a55933b5e71e178916e629f776b95 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:57:50 +0800 Subject: [PATCH 37/46] docs: trim CI cache tracking guidance --- docs/guide/github-actions-cache.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index 2dd061b47c..39d1d54339 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -119,16 +119,11 @@ vp run: cache hit, 1.10s saved. If GitHub restores a cache but Vite Task prints a cache miss, the Actions cache transport worked, but the task fingerprint changed. -## Keep Tracking Stable Across CI Runs +## Keep Task Tracking Stable -Vite Task's [automatic tracking](/guide/automatic-tracking) records file reads, missing-file probes, and directory listings. In CI, a command can read files that describe the dependency install or tool state rather than source behavior. Those reads can change between runs and cause misses after a successful GitHub cache restore. +GitHub Actions cache only restores the Vite Task cache directory. Vite Task still checks each restored entry before replaying it. -Treat these cases by root cause: - -- **Dependency install metadata.** Package managers and build tools can read install metadata to resolve packages, discover workspace layout, or configure file-system access. Track dependency identity with committed package manifests and lockfiles. For `vp build`, keep automatic tracking and add the lockfile as an input. Use explicit `input` globs only for commands with a small input set you can name. If that command writes files, review `output` in the same task config. -- **Tool-owned incremental state.** Tools such as TypeScript can write incremental state into a directory they also scan. A fresh checkout may lack that file, so the next run can miss because the directory listing changed. Move that state into a generated cache directory or use explicit task inputs. For TypeScript, set `--tsBuildInfoFile` to a generated cache location instead of writing `*.tsbuildinfo` next to source files. -- **Task outputs.** If a task output also appears in the input fingerprint, deleting the output causes a miss instead of an output restore. Keep generated files out of `input`, then use `output` to choose which files Vite Task restores. -- **Absolute arguments.** Vite Task stores command arguments in the fingerprint. If a command receives a different absolute checkout path between runs, it can miss with `args changed`. GitHub-hosted runners check out a repository under a stable path unless you override the checkout path. On self-hosted runners, keep the working directory stable or avoid absolute arguments. +If GitHub restores a cache but `vp run` prints a cache miss, fix the task fingerprint before changing the Actions cache key. See [Automatic Tracking](/guide/automatic-tracking) and [`run.tasks`](/config/run#tasks). ## Choose A Cache Key From 18eabe982bc82b261729371247080558aeb24d3c Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 02:59:15 +0800 Subject: [PATCH 38/46] docs: remove setup-vp cache reference --- docs/guide/github-actions-cache.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index 39d1d54339..c6ab91a99b 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -11,8 +11,6 @@ GitHub Actions cache and Vite Task make separate decisions: 1. `actions/cache` restores and saves the cache directory based on the key in your workflow. 2. Vite Task uses the restored cache directory and replays only the tasks whose fingerprints still match. -This cache is separate from dependency caching. Keep using [`setup-vp` cache support](/guide/ci) for package installs, then restore the Vite Task cache after dependencies are installed. - ## Before You Start Use this workflow when all of these are true: From 37e1f911065ca6b3561878cf491b0c1982f763da Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:02:53 +0800 Subject: [PATCH 39/46] docs: explain when to skip Actions cache --- docs/guide/github-actions-cache.md | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index c6ab91a99b..caaa61b128 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -22,6 +22,13 @@ Use this workflow when all of these are true: Fix local misses first. GitHub Actions cache can move Vite Task's local cache directory between runs, but it cannot make an unstable task cacheable. +## When To Skip GitHub Actions Cache + +You may not need to restore Vite Task cache across GitHub Actions runs in these cases: + +- The task is already fast enough. Cache restore and save steps add overhead, so short tasks can finish faster without this workflow. +- The cache is expensive to move between runs. Vite Task can still save time when the same task runs more than once in one workflow run. Across workflow runs, GitHub must download and upload the cache, so a large task cache can cost more time than rerunning the task. + ## 1. Define Cacheable CI Tasks Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache. Define a task in `vite.config.ts` for each command you want to cache in CI: @@ -141,18 +148,3 @@ Include: - A per-run value such as `github.run_id` and `github.run_attempt`, because GitHub cache entries are immutable. If a dependency file affects a task result, track it in the task fingerprint rather than the GitHub Actions key. - -## Limitations And Workarounds - -- **Cache entries are immutable.** Use a unique primary key per run and restore prefixes. GitHub will not update an existing cache entry in place. -- **Fork pull requests may be restore-only.** GitHub can allow forked pull request runs to restore existing caches without saving new entries. Populate shared caches from trusted branch or default-branch runs. -- **GitHub evicts caches.** GitHub removes caches that have not been accessed for over 7 days. It also evicts least-recently-used entries when repository cache storage exceeds its limit, which defaults to 10 GB. If this causes churn, narrow what you cache, delete stale entries, or increase the repository cache limit in GitHub settings. -- **Cache scope is branch-aware.** Workflow runs can restore caches from the current branch and the default branch. Pull request merge-ref caches have limited scope and help re-runs of the same pull request. See [GitHub's dependency caching reference](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) for the full branch and tag rules. -- **Secrets can leak through cache contents.** Vite Task caches terminal output and configured output files. Keep secrets out of task logs and generated files that you cache. -- **Output tracking can be too broad or too narrow.** By default, Vite Task restores files that the task writes. Use `output` globs such as `['dist/**']` when you want to narrow restoration. Use `{ auto: true }` with extra globs when you want automatic write tracking plus extra files. -- **Failed tasks are not cached.** Vite Task saves successful task results. Fix failing lint, test, or build commands before expecting cache reuse. -- **Toolchain changes can start cold.** Vite Task uses schema-versioned cache directories. If a restored cache was written by an incompatible version, Vite Task ignores those entries and reruns the task. - -::: tip -Restore after dependency install because the default cache path lives under `node_modules`. If your workflow must restore before install, set a stable absolute `VITE_CACHE_PATH` outside `node_modules` for all `vp run` steps and cache that directory instead. -::: From f4399350560dbca7bded2d9d281d42fa660ba312 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:06:09 +0800 Subject: [PATCH 40/46] docs: add Actions cache eviction guidance --- docs/guide/github-actions-cache.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index caaa61b128..f4a5383081 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -148,3 +148,17 @@ Include: - A per-run value such as `github.run_id` and `github.run_attempt`, because GitHub cache entries are immutable. If a dependency file affects a task result, track it in the task fingerprint rather than the GitHub Actions key. + +## Manage Cache Eviction And Scope + +GitHub evicts caches based on its cache retention and repository storage rules. Cache scope is also branch-aware: workflow runs can restore caches from the current branch and the default branch, while pull request merge-ref caches have limited scope. + +Vite Task can clean the whole task cache, but it does not currently evict individual task entries by age or size. As new task entries and output archives are saved, `node_modules/.vite/task-cache` can keep growing. + +Use GitHub Actions cache as the eviction boundary: + +- Keep the cached `path` limited to the Vite Task cache directory. +- Keep the restore prefix scoped to compatible runners, such as the same OS and architecture. +- Delete stale GitHub Actions cache entries, save caches from fewer workflows, or adjust the repository cache limit if cache size causes churn. + +See [GitHub's cache reference](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) for the current eviction and scope rules. From d9ea8fee708b0ef9cd09294727306c12d2b475a0 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:07:04 +0800 Subject: [PATCH 41/46] docs: emphasize measuring Actions cache value --- docs/guide/github-actions-cache.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index f4a5383081..f506d78f41 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -22,12 +22,14 @@ Use this workflow when all of these are true: Fix local misses first. GitHub Actions cache can move Vite Task's local cache directory between runs, but it cannot make an unstable task cacheable. -## When To Skip GitHub Actions Cache +## Measure Before Caching Across Runs + +Measure before you add GitHub Actions cache for Vite Task. Compare workflow duration with and without the restore and save steps. Check both the GitHub cache step time and the `vp run` time. You may not need to restore Vite Task cache across GitHub Actions runs in these cases: - The task is already fast enough. Cache restore and save steps add overhead, so short tasks can finish faster without this workflow. -- The cache is expensive to move between runs. Vite Task can still save time when the same task runs more than once in one workflow run. Across workflow runs, GitHub must download and upload the cache, so a large task cache can cost more time than rerunning the task. +- The cache is expensive to move between runs. Vite Task can still save time when the same task runs more than once in one workflow run. Across workflow runs, GitHub must download and upload the cache. If that transfer time is greater than rerunning the task, skip this workflow. ## 1. Define Cacheable CI Tasks From 6ecd7f5d3c97e71709d263cb5ae3858dcf92342b Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:10:17 +0800 Subject: [PATCH 42/46] docs: tighten Actions cache guidance --- docs/guide/github-actions-cache.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index f506d78f41..bd17306180 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -106,11 +106,11 @@ jobs: key: ${{ steps.vite-task-cache.outputs.cache-primary-key }} ``` -The primary key includes `github.run_id` and `github.run_attempt` so each successful run can save a new immutable cache entry. The restore prefix lets GitHub restore the newest cache for the same operating system and architecture. Vite Task checks the restored entries before replaying a task. +The primary key includes `github.run_id` and `github.run_attempt` so each successful run can save a new immutable cache entry. The restore prefix lets GitHub restore the newest cache for the same operating system and architecture. Leave task inputs, including source files and lockfiles, out of the GitHub Actions key. Vite Task fingerprints them. If they change the Actions key, GitHub can skip useful restores before Vite Task decides which tasks still hit. -For workspaces, restore the task cache from the workspace root. Then run the same workspace targets you use locally, such as `vp run -t @my/app#build`. Vite Task checks each restored entry before replaying it, including tasks from workspace dependencies. +For workspaces, restore the task cache from the workspace root. Then run the same workspace targets you use locally, such as `vp run -t @my/app#build`. The same cache covers tasks from workspace dependencies. ## 3. Verify In The Logs @@ -128,8 +128,6 @@ If GitHub restores a cache but Vite Task prints a cache miss, the Actions cache ## Keep Task Tracking Stable -GitHub Actions cache only restores the Vite Task cache directory. Vite Task still checks each restored entry before replaying it. - If GitHub restores a cache but `vp run` prints a cache miss, fix the task fingerprint before changing the Actions cache key. See [Automatic Tracking](/guide/automatic-tracking) and [`run.tasks`](/config/run#tasks). ## Choose A Cache Key @@ -142,7 +140,7 @@ restore-keys: | vite-task-${{ runner.os }}-${{ runner.arch }}- ``` -The exact key misses on each new run because the key contains `github.run_id` and `github.run_attempt`. GitHub then searches the restore prefix and restores the newest matching cache. Vite Task checks restored entries before replaying a task. +The exact key misses on each new run because the key contains `github.run_id` and `github.run_attempt`. GitHub then searches the restore prefix and restores the newest matching cache. Include: From 7265c316c6dfe984c44ab01babc3f1167fbfebbe Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:18:36 +0800 Subject: [PATCH 43/46] docs: polish task cache guidance --- docs/config/run.md | 4 ++-- docs/guide/automatic-tracking.md | 6 +++--- docs/guide/cache.md | 2 +- docs/guide/github-actions-cache.md | 2 +- docs/guide/run.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/config/run.md b/docs/config/run.md index 8ab73c1d51..011a5b8b08 100644 --- a/docs/config/run.md +++ b/docs/config/run.md @@ -142,7 +142,7 @@ Dependencies can reference tasks in other packages using the `package#task` form dependsOn: ['@my/core#build', '@my/utils#lint']; ``` -Use the object form `{ task: string, from: DependsOnFrom }` to reference tasks from all dependencies: +Use the object form `{ task: string, from: DependsOnFrom }` to reference tasks from packages listed in dependency fields: ```ts [vite.config.ts] tasks: { @@ -153,7 +153,7 @@ tasks: { } ``` -For the example above, Vite Task reads the declaring package's direct `dependencies` and `devDependencies`, and runs `build` task in each dependency if it defines one. Packages without `build` are skipped. +For the example above, Vite Task reads the declaring package's direct `dependencies` and `devDependencies`, and runs the `build` task in each dependency that defines one. Packages without `build` are skipped. See [Task Dependencies](/guide/run#task-dependencies) for details on how explicit and topological dependencies interact. diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index df1a32e874..d2e75c0c6e 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -1,6 +1,6 @@ # Automatic Tracking -Automatic tracking is how Vite Task learns what to cache for a task without explicit configurations. +Automatic tracking is how Vite Task learns what to cache for a task without explicit config. When you run a cache-enabled task, Vite Task observes the task's execution and records what files were read and written, as well as any metadata reported by the task. On the next run, Vite Task decides whether the cache misses or hits based on the recorded fingerprint. @@ -19,7 +19,7 @@ Vite Task starts with file system tracking for any command. A cache-reporting to ## File System Tracking -File system tracking applies to every task to be cached. If you omit [`input`](/config/run#input), Vite Task tracks the files a command reads while it runs: +File system tracking applies to every cache-enabled task. If you omit [`input`](/config/run#input), Vite Task tracks the files a command reads while it runs: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; @@ -116,7 +116,7 @@ export default defineConfig({ }); ``` -Manual config still wins. Add `input`, `output`, `env`, or `untrackedEnv` when your project has behavior that Vite cannot report. +Manual config overrides reported metadata. Add `input`, `output`, `env`, or `untrackedEnv` when your project has behavior that Vite cannot report. Vite+ supports cooperative tracking for `vp build` today. It will extend this support to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client). diff --git a/docs/guide/cache.md b/docs/guide/cache.md index 455215eacb..a532dea689 100644 --- a/docs/guide/cache.md +++ b/docs/guide/cache.md @@ -50,7 +50,7 @@ Vite Task uses [automatic tracking](/guide/automatic-tracking) to learn what eac - **File system tracking:** Vite Task records file reads, missing-file probes, directory listings, and written output files for every task with cache enabled. - **Cooperative tracking:** cache-reporting tools can report metadata that file system tracking cannot infer. Vite+ supports this for `vp build` today. -Use [`input`](/config/run#input) and [`output`](/config/run#output) together when a task needs manual tracking rules. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. +Use [`input`](/config/run#input) or [`output`](/config/run#output) when a task needs manual tracking rules. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit. ```ts [vite.config.ts] tasks: { diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index bd17306180..ef787b4002 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -29,7 +29,7 @@ Measure before you add GitHub Actions cache for Vite Task. Compare workflow dura You may not need to restore Vite Task cache across GitHub Actions runs in these cases: - The task is already fast enough. Cache restore and save steps add overhead, so short tasks can finish faster without this workflow. -- The cache is expensive to move between runs. Vite Task can still save time when the same task runs more than once in one workflow run. Across workflow runs, GitHub must download and upload the cache. If that transfer time is greater than rerunning the task, skip this workflow. +- Cache transfer takes longer than the task. Vite Task can still save time when the same task runs more than once in one workflow run. Across workflow runs, GitHub must download and upload the cache. If that transfer time is greater than rerunning the task, skip this workflow. ## 1. Define Cacheable CI Tasks diff --git a/docs/guide/run.md b/docs/guide/run.md index cf3be3d2f8..6b02cbfb36 100644 --- a/docs/guide/run.md +++ b/docs/guide/run.md @@ -113,7 +113,7 @@ dependsOn: [ ]; ``` -Use the object form when you need to reference all tasks with a given name from the current package's dependencies: +Use the object form when you need to reference tasks with a given name from packages listed in the current package's dependencies: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; From 442bd9e52c129c242975e636d9ccc075f739935c Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:21:38 +0800 Subject: [PATCH 44/46] docs: refine task cache wording --- docs/config/run.md | 2 +- docs/guide/github-actions-cache.md | 4 ++-- docs/guide/run.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/config/run.md b/docs/config/run.md index 011a5b8b08..4cd0816a1c 100644 --- a/docs/config/run.md +++ b/docs/config/run.md @@ -142,7 +142,7 @@ Dependencies can reference tasks in other packages using the `package#task` form dependsOn: ['@my/core#build', '@my/utils#lint']; ``` -Use the object form `{ task: string, from: DependsOnFrom }` to reference tasks from packages listed in dependency fields: +Use the object form `{ task: string, from: DependsOnFrom }` to reference tasks from all dependencies: ```ts [vite.config.ts] tasks: { diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index ef787b4002..ad9a626b7c 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -1,10 +1,10 @@ # GitHub Actions Cache ::: warning Experimental -Reusing Vite Task cache through GitHub Actions cache is experimental. Validate the workflow in your project before you depend on it for CI time savings. +Reusing Vite Task cache across GitHub Actions runs is experimental. Test and measure it in your project before relying on it in CI. ::: -Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. You can restore that directory in a later GitHub Actions run, then let Vite Task decide whether each task matches the current command, environment, inputs, and outputs. +Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. Restore that directory in later GitHub Actions runs. Vite Task replays only entries whose task fingerprint still matches the current command, environment, inputs, and outputs. GitHub Actions cache and Vite Task make separate decisions: diff --git a/docs/guide/run.md b/docs/guide/run.md index 6b02cbfb36..cf3be3d2f8 100644 --- a/docs/guide/run.md +++ b/docs/guide/run.md @@ -113,7 +113,7 @@ dependsOn: [ ]; ``` -Use the object form when you need to reference tasks with a given name from packages listed in the current package's dependencies: +Use the object form when you need to reference all tasks with a given name from the current package's dependencies: ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; From 1c21b7fe97a18780cf3cee830cbde544d81fc35c Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:23:13 +0800 Subject: [PATCH 45/46] docs: simplify Actions cache intro --- docs/guide/github-actions-cache.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index ad9a626b7c..2c69239051 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -4,7 +4,7 @@ Reusing Vite Task cache across GitHub Actions runs is experimental. Test and measure it in your project before relying on it in CI. ::: -Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. Restore that directory in later GitHub Actions runs. Vite Task replays only entries whose task fingerprint still matches the current command, environment, inputs, and outputs. +Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. Restore that directory in later GitHub Actions runs so Vite Task can reuse valid cache entries. GitHub Actions cache and Vite Task make separate decisions: From cf73255125b057d371cc4ce600cedaf85f6a4d01 Mon Sep 17 00:00:00 2001 From: wan9chi Date: Wed, 1 Jul 2026 03:27:42 +0800 Subject: [PATCH 46/46] docs: tighten task cache wording --- docs/guide/automatic-tracking.md | 6 +++--- docs/guide/github-actions-cache.md | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/guide/automatic-tracking.md b/docs/guide/automatic-tracking.md index d2e75c0c6e..28183834e1 100644 --- a/docs/guide/automatic-tracking.md +++ b/docs/guide/automatic-tracking.md @@ -1,8 +1,8 @@ # Automatic Tracking -Automatic tracking is how Vite Task learns what to cache for a task without explicit config. +Automatic tracking is how Vite Task learns what a task needs for caching without explicit config. -When you run a cache-enabled task, Vite Task observes the task's execution and records what files were read and written, as well as any metadata reported by the task. On the next run, Vite Task decides whether the cache misses or hits based on the recorded fingerprint. +When you run a cache-enabled task, Vite Task observes the task's execution and records what files were read and written, as well as any metadata reported by the task. On the next run, Vite Task uses the recorded fingerprint to decide whether to replay the cache or run the task. Use this page when you need to understand why a task hits or misses the cache, or when you need to decide whether to add `input`, `output`, `env`, or `untrackedEnv` config. @@ -92,7 +92,7 @@ Set `input: []` when no files should affect the cache fingerprint. Set `output: ## Cooperative Tracking -File system tracking sees access. It cannot always see intent. +File system tracking records access. It cannot know why a tool used each path. `vp build` knows more about a Vite build than Vite Task can infer from file access. When `vp build` runs with cache enabled, Vite reports that metadata to Vite Task. Vite Task merges the report with file system tracking to build a more accurate cache fingerprint. diff --git a/docs/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md index 2c69239051..a6dbdccb8d 100644 --- a/docs/guide/github-actions-cache.md +++ b/docs/guide/github-actions-cache.md @@ -4,7 +4,7 @@ Reusing Vite Task cache across GitHub Actions runs is experimental. Test and measure it in your project before relying on it in CI. ::: -Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. Restore that directory in later GitHub Actions runs so Vite Task can reuse valid cache entries. +Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. Restore that directory in later GitHub Actions runs so Vite Task can reuse previous task results. GitHub Actions cache and Vite Task make separate decisions: @@ -110,7 +110,7 @@ The primary key includes `github.run_id` and `github.run_attempt` so each succes Leave task inputs, including source files and lockfiles, out of the GitHub Actions key. Vite Task fingerprints them. If they change the Actions key, GitHub can skip useful restores before Vite Task decides which tasks still hit. -For workspaces, restore the task cache from the workspace root. Then run the same workspace targets you use locally, such as `vp run -t @my/app#build`. The same cache covers tasks from workspace dependencies. +For monorepos, restore the task cache from the workspace root. Then run the same `vp run` commands you use locally, such as `vp run -t @my/app#build`. Vite Task can reuse results for the requested package and the packages it depends on. ## 3. Verify In The Logs @@ -124,7 +124,7 @@ $ vp build ◉ cache hit, replaying vp run: cache hit, 1.10s saved. ``` -If GitHub restores a cache but Vite Task prints a cache miss, the Actions cache transport worked, but the task fingerprint changed. +If GitHub restores a cache but Vite Task prints a cache miss, the workflow restored the cache directory, but the task fingerprint changed. ## Keep Task Tracking Stable @@ -140,7 +140,7 @@ restore-keys: | vite-task-${{ runner.os }}-${{ runner.arch }}- ``` -The exact key misses on each new run because the key contains `github.run_id` and `github.run_attempt`. GitHub then searches the restore prefix and restores the newest matching cache. +The primary key is unique for each run because it contains `github.run_id` and `github.run_attempt`. GitHub then searches the restore prefix and restores the newest matching cache. Include: @@ -153,12 +153,12 @@ If a dependency file affects a task result, track it in the task fingerprint rat GitHub evicts caches based on its cache retention and repository storage rules. Cache scope is also branch-aware: workflow runs can restore caches from the current branch and the default branch, while pull request merge-ref caches have limited scope. -Vite Task can clean the whole task cache, but it does not currently evict individual task entries by age or size. As new task entries and output archives are saved, `node_modules/.vite/task-cache` can keep growing. +Vite Task can clear the whole task cache, but it does not currently evict individual task entries by age or size. As new task entries and output archives are saved, `node_modules/.vite/task-cache` can keep growing. -Use GitHub Actions cache as the eviction boundary: +Manage size at the GitHub Actions cache layer: - Keep the cached `path` limited to the Vite Task cache directory. - Keep the restore prefix scoped to compatible runners, such as the same OS and architecture. -- Delete stale GitHub Actions cache entries, save caches from fewer workflows, or adjust the repository cache limit if cache size causes churn. +- Delete stale GitHub Actions cache entries, save caches from fewer workflows, or adjust the repository cache limit if large caches cause frequent evictions. See [GitHub's cache reference](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) for the current eviction and scope rules.