Skip to content

Commit 04a3f2f

Browse files
claudeclaude
committed
docs: update cache decision tree to match --cache implementation
--cache acts as cache: true, overriding both cache.tasks and cache.scripts (not just scripts). Restructure the decision tree to reflect that --cache/--no-cache are resolved first as global overrides, then per-task cache: false is checked, then the task-vs-script distinction determines which global switch applies. https://claude.ai/code/session_01AYbt3E5j8Adk9NB7Sprkah
1 parent 91b6059 commit 04a3f2f

1 file changed

Lines changed: 175 additions & 0 deletions

File tree

‎docs/task-configuration.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Task Configuration
2+
3+
Tasks are configured in the `run` section of your `vite.config.ts`. There are two ways tasks can exist: **explicit task definitions** and **package.json scripts**.
4+
5+
## Configuration Location
6+
7+
Each package can have its own `vite.config.ts` that configures tasks for that package:
8+
9+
```ts
10+
// packages/app/vite.config.ts
11+
import { defineConfig } from 'vite-plus';
12+
13+
export default defineConfig({
14+
run: {
15+
tasks: {
16+
build: {
17+
command: 'tsc',
18+
dependsOn: ['lint'],
19+
cache: true,
20+
envs: ['NODE_ENV'],
21+
passThroughEnvs: ['CI'],
22+
},
23+
lint: {
24+
command: 'vp lint',
25+
},
26+
deploy: {
27+
command: 'deploy-script --prod',
28+
cache: false,
29+
},
30+
},
31+
},
32+
});
33+
```
34+
35+
## Task Definition Schema
36+
37+
Each task supports these fields:
38+
39+
| Field | Type | Default | Description |
40+
| ----------------- | ---------- | ------------------- | ---------------------------------------------------------------------------------------------- |
41+
| `command` | `string` | — | The shell command to run. If omitted, falls back to the package.json script of the same name. |
42+
| `cwd` | `string` | package root | Working directory relative to the package root. |
43+
| `dependsOn` | `string[]` | `[]` | Explicit task dependencies. See [Task Orchestration](./task-orchestration.md). |
44+
| `cache` | `boolean` | `true` | Whether to cache this task's output. |
45+
| `envs` | `string[]` | `[]` | Environment variables to include in the cache fingerprint. |
46+
| `passThroughEnvs` | `string[]` | (built-in defaults) | Environment variables passed to the process but NOT included in the cache fingerprint. |
47+
| `inputs`\* | `Array` | auto-inferred | Which files to track for cache invalidation. See [Caching — Inputs](./caching.md#task-inputs). |
48+
49+
## Scripts vs Tasks
50+
51+
Vite Task recognizes two sources of runnable commands:
52+
53+
### 1. Package.json Scripts
54+
55+
Any `"scripts"` entry in a package's `package.json` is automatically available:
56+
57+
```json
58+
// packages/app/package.json
59+
{
60+
"name": "@my/app",
61+
"scripts": {
62+
"build": "tsc",
63+
"test": "vitest run",
64+
"dev": "vite dev"
65+
}
66+
}
67+
```
68+
69+
These scripts can be run directly with `vp run build` (from within the `packages/app` directory).
70+
71+
### 2. Explicit Task Definitions
72+
73+
Tasks defined in a package's `vite.config.ts` only affect that package. A task definition applies when:
74+
75+
- The package has a matching script in `package.json`, or
76+
- The task itself specifies a `command`
77+
78+
```ts
79+
// packages/app/vite.config.ts
80+
export default defineConfig({
81+
run: {
82+
tasks: {
83+
build: {
84+
// No command — uses this package's "build" script from package.json
85+
dependsOn: ['lint'],
86+
envs: ['NODE_ENV'],
87+
},
88+
},
89+
},
90+
});
91+
```
92+
93+
In this example, `build` runs `@my/app`'s own `package.json` `"build"` script but with the added `dependsOn` and cache configuration.
94+
95+
**Conflict rule:** If both the task definition and the `package.json` script specify a command, it's an error. Either define the command in `vite.config.ts` or in `package.json` — not both.
96+
97+
## Global Cache Configuration\*
98+
99+
The `cache` field is only allowed in the **workspace root** `vite.config.ts` and controls workspace-wide cache behavior:
100+
101+
```ts
102+
// vite.config.ts (workspace root only)
103+
export default defineConfig({
104+
run: {
105+
cache: { scripts: true, tasks: true },
106+
},
107+
});
108+
```
109+
110+
| Setting | Type | Default | Meaning |
111+
| --------------- | ------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
112+
| `cache` | `boolean \| { scripts, tasks }` | `{ scripts: false, tasks: true }` | Global cache toggle |
113+
| `cache.tasks` | `boolean` | `true` | When `true`, respects individual task cache config. When `false`, disables all task caching globally. |
114+
| `cache.scripts` | `boolean` | `false` | When `true`, caches `package.json` scripts even without explicit task entries. |
115+
116+
Shorthands:
117+
118+
- `cache: true` → `{ scripts: true, tasks: true }`
119+
- `cache: false` → `{ scripts: false, tasks: false }`
120+
121+
### CLI Overrides\*
122+
123+
You can override the global cache config per invocation:
124+
125+
```bash
126+
vp run build --cache # Force all caching on (scripts + tasks)
127+
vp run build --no-cache # Force all caching off
128+
```
129+
130+
### When Is Caching Enabled?
131+
132+
A command run by `vp run` is either a **task** (has an entry in `vite.config.ts`) or a **script** (only exists in `package.json` with no corresponding task entry). A script that has a matching task entry is treated as a task.
133+
134+
```
135+
--no-cache on the command line?
136+
├─ YES → NOT CACHED (overrides everything)
137+
└─ NO
138+
│
139+
--cache on the command line?
140+
├─ YES → acts as cache: true (sets scripts: true, tasks: true)
141+
└─ NO → uses workspace config
142+
│
143+
Per-task cache set to false?
144+
├─ YES → NOT CACHED (--cache does NOT override this)
145+
└─ NO or not set
146+
│
147+
Does the command have a task entry in vite.config.ts?
148+
│
149+
├─ YES (task) ──────────────────────────────────────────
150+
│ │
151+
│ Global cache.tasks enabled? (default: true, or true via --cache)
152+
│ ├─ NO → NOT CACHED
153+
│ └─ YES → CACHED <----- this is the default for tasks
154+
│
155+
└─ NO (script) ─────────────────────────────────────────
156+
│
157+
Global cache.scripts enabled? (default: false, or true via --cache)
158+
├─ YES → CACHED
159+
└─ NO → NOT CACHED <----- this is the default for scripts
160+
```
161+
162+
In short: **tasks are cached by default, scripts are not.** `--no-cache` turns off caching for everything. `--cache` is equivalent to `cache: true` — it enables both `cache.tasks` and `cache.scripts`, but cannot override a task's per-task `cache: false`.
163+
164+
## Compound Commands and Nested `vp run`
165+
166+
Commands joined with `&&` are split into independently-cached sub-tasks. Commands containing `vp run` calls are expanded at plan time into the execution graph. Both features work in task `command` fields and `package.json` scripts. See [Task Orchestration](./task-orchestration.md#compound-commands) for details.
167+
168+
## Environment Variables
169+
170+
See [Caching — Environment Variables](./caching.md#environment-variables) for full details on how `envs` and `passThroughEnvs` work with the cache system.
171+
172+
Quick summary:
173+
174+
- **`envs`**: Included in the cache fingerprint. Changing a value here invalidates the cache.
175+
- **`passThroughEnvs`**: Passed to the process but NOT fingerprinted. Changing values here does NOT invalidate the cache.

0 commit comments

Comments
 (0)