diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 200c0f922a..ab43ee2122 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -16,6 +16,14 @@ const taskRunnerGuideItems = [ text: 'Task Caching', link: '/guide/cache', }, + { + text: 'Automatic Tracking', + link: '/guide/automatic-tracking', + }, + { + 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..4cd0816a1c 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 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. ### `cache` @@ -168,17 +183,19 @@ 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. + +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 -$ 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 +208,17 @@ 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). + +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: - **System:** `HOME`, `USER`, `PATH`, `SHELL`, `LANG`, `TZ` - **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 - **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 details and when to add manual config. **Exclude files** from automatic tracking: @@ -270,26 +291,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 +332,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/automatic-tracking.md b/docs/guide/automatic-tracking.md new file mode 100644 index 0000000000..28183834e1 --- /dev/null +++ b/docs/guide/automatic-tracking.md @@ -0,0 +1,133 @@ +# Automatic Tracking + +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 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. + +## Tracking Tiers + +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
  • 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. + +## File System Tracking + +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'; + +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. + +### 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 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. + +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`. + +### 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. + +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] +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. + output: ['dist/**'], + }, +} +``` + +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. + input: ['src/**', 'vite.config.ts'], + }, +} +``` + +Set `input: []` when no files should affect the cache fingerprint. Set `output: []` when no files should be restored on a cache hit. + +## Cooperative Tracking + +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. + +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 exclusions for temporary paths like `node_modules/.vite-temp` + +You only need to define the task with `vp build`: + +```ts [vite.config.ts] +import { defineConfig } from 'vite-plus'; + +export default defineConfig({ + run: { + tasks: { + build: 'vp build', + }, + }, +}); +``` + +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). + +## When To Add Manual Config + +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 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']` | +| Pass an env var without fingerprinting it | `untrackedEnv: ['GITHUB_ACTIONS']` | diff --git a/docs/guide/cache.md b/docs/guide/cache.md index fd034e0249..a532dea689 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? +3. **Inputs:** did any input 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/**'], - }, -} -``` +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: ``` $ 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 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 @@ -56,29 +43,21 @@ 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 - -Vite Task tracks which files each command reads during execution. When a task runs, it records which files the process opens, such as your `.ts` source files, `vite.config.ts`, and `package.json`, and records their content hashes. On the next run, it re-checks those hashes to determine if anything changed. - -This means caching works out of the box for most commands without any configuration. Vite Task also records: +## Automatic Tracking -- **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. +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: -### Avoiding Overly Broad Input Tracking +- **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. -Automatic tracking can sometimes include more files than necessary, causing unnecessary cache misses: - -- **Tool cache files:** some tools maintain their own cache, such as TypeScript's `.tsbuildinfo` or Cargo's `target/`. These files may change between runs even when your source code has not, causing unnecessary cache invalidation. -- **Directory listings:** when a command scans a directory, such as when globbing for `**/*.js`, Vite Task sees the directory read but not the glob pattern. Any file added or removed in that directory, even unrelated ones, invalidates the cache. - -Use the [`input`](/config/run#input) option to exclude files or to replace automatic tracking with explicit file patterns: +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: { build: { - command: 'tsc', - input: [{ auto: true }, '!**/*.tsbuildinfo'], + command: 'node build.mjs', + input: [{ auto: true }, '!dist/**'], + output: ['dist/**'], }, } ``` @@ -98,7 +77,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#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/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..a6dbdccb8d --- /dev/null +++ b/docs/guide/github-actions-cache.md @@ -0,0 +1,164 @@ +# GitHub Actions Cache + +::: warning Experimental +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 previous task results. + +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. + +## 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 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. + +## 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. +- 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 + +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'; + +export default defineConfig({ + run: { + tasks: { + build: 'vp build', + lint: 'vp lint', + }, + }, +}); +``` + +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: + +```bash +vp run build +vp run build # should print "cache hit" +vp run lint +vp run lint # should print "cache hit" +``` + +## 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' + + - run: vp install + + - name: Restore Vite Task cache + id: vite-task-cache + uses: actions/cache/restore@v6 + with: + path: node_modules/.vite/task-cache + key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }} + restore-keys: | + vite-task-${{ runner.os }}-${{ runner.arch }}- + + - run: vp run lint + - run: vp run build + + - name: Save Vite Task cache + if: success() + uses: actions/cache/save@v6 + with: + path: node_modules/.vite/task-cache + key: ${{ steps.vite-task-cache.outputs.cache-primary-key }} +``` + +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 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 + +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: + +```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 workflow restored the cache directory, but the task fingerprint changed. + +## Keep Task Tracking Stable + +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 + +Use a rolling primary key plus a restore prefix: + +```yaml [.github/workflows/ci.yml] +key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }} +restore-keys: | + vite-task-${{ runner.os }}-${{ runner.arch }}- +``` + +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: + +- `runner.os` and `runner.arch`, because outputs and native tools can be platform-specific. +- 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 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. + +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 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. diff --git a/docs/guide/run.md b/docs/guide/run.md index 58d8350521..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 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 [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'; @@ -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