Skip to content

Commit 61d37e5

Browse files
fengmk2fengmk2
authored
Merge branch 'main' into release/v0.2.2
2 parents 9d225ab + 8696d85 commit 61d37e5

7 files changed

Lines changed: 426 additions & 50 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ const taskRunnerGuideItems = [
1515
{
1616
text: 'Task Caching',
1717
link: '/guide/cache',
18+
items: [
19+
{ text: 'Automatic Data Tracking', link: '/guide/automatic-data-tracking' },
20+
{ text: 'GitHub Actions Cache', link: '/guide/github-actions-cache' },
21+
],
1822
},
1923
{
2024
text: 'Running Binaries',

‎docs/config/run.md‎

Lines changed: 61 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -120,9 +120,11 @@ Commands joined with `&&` (or supplied as an array) are automatically split into
120120

121121
### `dependsOn`
122122

123-
- **Type:** `string[]`
123+
- **Type:** `Array<string | { task: string, from: DependsOnFrom }>`
124124
- **Default:** `[]`
125125

126+
`from` accepts the dependency types `"dependencies"`, `"devDependencies"`, `"peerDependencies"`, or an array of those values, such as `["dependencies", "devDependencies"]`.
127+
126128
Tasks that must complete successfully before this one starts.
127129

128130
```ts [vite.config.ts]
@@ -140,6 +142,19 @@ Dependencies can reference tasks in other packages using the `package#task` form
140142
dependsOn: ['@my/core#build', '@my/utils#lint'];
141143
```
142144

145+
Use the object form `{ task: string, from: DependsOnFrom }` to reference tasks from all dependencies:
146+
147+
```ts [vite.config.ts]
148+
tasks: {
149+
test: {
150+
command: 'vp test',
151+
dependsOn: [{ task: 'build', from: ['dependencies', 'devDependencies'] }],
152+
},
153+
}
154+
```
155+
156+
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.
157+
143158
See [Task Dependencies](/guide/run#task-dependencies) for details on how explicit and topological dependencies interact.
144159

145160
### `cache`
@@ -168,17 +183,19 @@ Environment variables included in the cache fingerprint. When any listed variabl
168183
```ts [vite.config.ts]
169184
tasks: {
170185
build: {
171-
command: 'vp build',
186+
command: 'node build.mjs',
172187
env: ['NODE_ENV'],
173188
},
174189
}
175190
```
176191

177-
Wildcard patterns are supported: `VITE_*` matches all variables starting with `VITE_`.
192+
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.
193+
194+
For `vp build`, Vite reports Vite environment variables through [automatic tracking](/guide/automatic-data-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.
178195

179196
```bash
180197
$ NODE_ENV=development vp run build # first run
181-
$ NODE_ENV=production vp run build # cache miss: variable changed
198+
$ NODE_ENV=production vp run build # cache miss: env 'NODE_ENV' changed
182199
```
183200

184201
### `untrackedEnv`
@@ -191,13 +208,17 @@ Environment variables passed to the task process but **not** included in the cac
191208
```ts [vite.config.ts]
192209
tasks: {
193210
build: {
194-
command: 'vp build',
211+
command: 'node build.mjs',
195212
untrackedEnv: ['CI', 'GITHUB_ACTIONS'],
196213
},
197214
}
198215
```
199216

200-
A set of common environment variables are automatically passed through to all tasks:
217+
`untrackedEnv` accepts the same wildcard and `!` exclusion patterns as [`env`](#env).
218+
219+
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-data-tracking#cooperative-tracking), leave it out of both `env` and `untrackedEnv`.
220+
221+
Vite Task passes a set of common environment variables to all tasks:
201222

202223
- **System:** `HOME`, `USER`, `PATH`, `SHELL`, `LANG`, `TZ`
203224
- **Node.js:** `NODE_OPTIONS`, `COREPACK_HOME`, `PNPM_HOME`
@@ -209,7 +230,7 @@ A set of common environment variables are automatically passed through to all ta
209230
- **Type:** `Array<string | { auto: boolean } | { pattern: string, base: "workspace" | "package" }>`
210231
- **Default:** `[{ auto: true }]` (auto-inferred)
211232

212-
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.
233+
Vite Task automatically detects which files a command uses. See [Automatic Data Tracking](/guide/automatic-data-tracking) for the details and when to add manual config.
213234

214235
**Exclude files** from automatic tracking:
215236

@@ -270,26 +291,41 @@ String glob patterns are resolved relative to the package directory by default.
270291

271292
### `output`
272293

273-
- **Type:** `Array<string | { pattern: string, base: "workspace" | "package" }>`
274-
- **Default:** `[]` (nothing is archived)
294+
- **Type:** `Array<string | { auto: boolean } | { pattern: string, base: "workspace" | "package" }>`
295+
- **Default:** automatic write tracking
296+
297+
Vite Task automatically archives files generated by a successful task run and restores them on a cache hit.
275298

276-
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.
299+
If you omit `output`, Vite Task uses automatic write tracking to choose those files. Add explicit `output` entries when you need to override which files are restored.
277300

278301
```ts [vite.config.ts]
279302
tasks: {
280303
build: {
281-
command: 'vp build',
304+
command: 'node build.mjs',
282305
output: ['dist/**', '!dist/cache/**'],
283306
},
284307
}
285308
```
286309

310+
Use `{ auto: true }` to keep automatic write tracking while adding explicit output globs.
311+
312+
This is useful when a task writes files that should not be restored from the cache. For example, exclude TypeScript `.tsbuildinfo` files:
313+
314+
```ts [vite.config.ts]
315+
tasks: {
316+
typecheck: {
317+
command: 'tsc --build',
318+
output: [{ auto: true }, '!*.tsbuildinfo'],
319+
},
320+
}
321+
```
322+
287323
If a task writes outside its own package, use the object form with `base: "workspace"`:
288324

289325
```ts [vite.config.ts]
290326
tasks: {
291327
build: {
292-
command: 'vp build',
328+
command: 'node build.mjs',
293329
output: [
294330
'dist/**',
295331
{ pattern: 'shared-artifacts/**', base: 'workspace' },
@@ -298,6 +334,19 @@ tasks: {
298334
}
299335
```
300336

337+
Set `output: []` to disable output restoration for a cached task:
338+
339+
```ts [vite.config.ts]
340+
tasks: {
341+
report: {
342+
command: 'node scripts/report.mjs',
343+
output: [],
344+
},
345+
}
346+
```
347+
348+
Unlike `cache: false`, `output: []` still lets Vite Task fingerprint the task. On a cache hit, Vite Task skips the command and replays its terminal output. Use this for local caches when the task's output files are already there and do not need to be restored.
349+
301350
### `cwd`
302351

303352
- **Type:** `string`

‎docs/guide/automatic-data-tracking.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Automatic Data Tracking
2+
3+
Automatic data tracking is how Vite Task learns what inputs a task needs for caching outputs without explicit config.
4+
5+
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.
6+
7+
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+
9+
## Tracking Tiers
10+
11+
Automatic data tracking has two tiers:
12+
13+
| Tier | Applies to | Records |
14+
| -------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15+
| File system tracking | All tasks with cache enabled | <ul><li>Files read by the command</li><li>Missing-file probes</li><li>Directory listings</li><li>Written output files</li></ul> |
16+
| Cooperative tracking | Cache-reporting tools (`vp build` today) | <ul><li>Environment variables reported by the tool</li><li>Tool-managed paths that should not be inputs or outputs, such as `node_modules/.vite-temp`</li></ul> |
17+
18+
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.
19+
20+
## File System Tracking
21+
22+
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:
23+
24+
```ts [vite.config.ts]
25+
import { defineConfig } from 'vite-plus';
26+
27+
export default defineConfig({
28+
run: {
29+
tasks: {
30+
build: {
31+
command: 'tsc',
32+
},
33+
},
34+
},
35+
});
36+
```
37+
38+
For this task, Vite Task records source files, config files, missing files the command checked, and directories the command scanned. Subsequent runs re-run the task when one of those tracked inputs changes.
39+
40+
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.
41+
42+
### Limitations
43+
44+
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.
45+
46+
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.
47+
48+
Use [`env`](/config/run#env) when a command needs an environment variable and the value should affect the cache, or [`untrackedEnv`](/config/run#untrackedenv) when the value should not affect the cache.
49+
50+
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`.
51+
52+
### Override Inputs And Outputs
53+
54+
[`input`](/config/run#input) controls what invalidates the cache. [`output`](/config/run#output) controls which files Vite Task restores on a cache hit.
55+
56+
Both options use the same syntax and can be configured separately.
57+
58+
- Omit the option to keep automatic tracking.
59+
- Add `{ auto: true }` to keep automatic tracking while adding glob rules.
60+
- Use string globs to include paths.
61+
- Use `!` globs to exclude paths.
62+
- Use `[]` to replace automatic tracking with an empty list.
63+
64+
```ts [vite.config.ts]
65+
tasks: {
66+
build: {
67+
command: 'node build.mjs',
68+
69+
// Keep automatic input tracking, but exclude `dist` from inputs.
70+
input: [{ auto: true }, '!dist/**'],
71+
72+
// Disable automatic output tracking and restore only `dist/**` on a cache hit.
73+
output: ['dist/**'],
74+
},
75+
}
76+
```
77+
78+
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:
79+
80+
```ts [vite.config.ts]
81+
tasks: {
82+
lint: {
83+
command: 'vp lint',
84+
// Disable automatic input tracking and fingerprint only these files.
85+
input: ['src/**', 'vite.config.ts'],
86+
},
87+
}
88+
```
89+
90+
Set `input: []` when no files should affect the cache fingerprint. This is rarely useful. For example, a download task can be cached when the same URL always serves the same file. No input files should be fingerprinted for this task, but changing the URL still invalidates the cache:
91+
92+
```ts [vite.config.ts]
93+
tasks: {
94+
downloadSchema: {
95+
command: 'curl -O https://example.com/schema.json',
96+
input: [],
97+
},
98+
}
99+
```
100+
101+
Set `output: []` when no files should be restored on a cache hit.
102+
103+
## Cooperative Tracking
104+
105+
File system tracking records access. It cannot know why a tool used each path.
106+
107+
`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.
108+
109+
For a standard Vite build, you do not need to add these entries yourself because Vite reports them automatically at runtime:
110+
111+
- `env: ['VITE_*']` or `env: ['NODE_ENV']`
112+
- `output: ['dist/**']`
113+
- input or output exclusions for temporary paths like `node_modules/.vite-temp`
114+
115+
You only need to define the task with `vp build`:
116+
117+
```ts [vite.config.ts]
118+
import { defineConfig } from 'vite-plus';
119+
120+
export default defineConfig({
121+
run: {
122+
tasks: {
123+
frontendBuild: 'vp build',
124+
},
125+
},
126+
});
127+
```
128+
129+
Run this task with `vpr frontendBuild` or `vp run frontendBuild`.
130+
131+
Manual config overrides reported metadata. Add `input`, `output`, `env`, or `untrackedEnv` when your project has behavior that Vite cannot report.
132+
133+
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).
134+
135+
## When To Add Manual Config
136+
137+
Add config when your project has behavior the command or tool cannot know.
138+
139+
| Case | Example |
140+
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
141+
| Exclude an output directory from inputs | `input: [{ auto: true }, '!dist/**']` |
142+
| Exclude a temporary generated file from input and output tracking | `input: [{ auto: true }, '!.tmp/config.mjs']`<br>`output: [{ auto: true }, '!.tmp/config.mjs']` |
143+
| Avoid automatic file tracking for a task | `input: ['src/**']`<br>`output: ['dist/**']` |
144+
| Track and pass an env var | `env: ['NODE_ENV']` |
145+
| Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` |

0 commit comments

Comments
 (0)