Run Config

You can configure Vite Task under the run field in vite.config.ts. Check out vp run to learn more about running scripts and tasks with Vite+.

vite.config.ts

import { defineConfig } from 'vite-plus';

export default defineConfig({
  run: {
    enablePrePostScripts: true,
    cache: {
      /* ... */
    },
    tasks: {
      /* ... */
    },
  },
});

run.enablePrePostScripts

• Type: boolean
• Default: true

Whether to automatically run preX/postX package.json scripts as lifecycle hooks when script X is executed.

When enabled (the default), running a script like test will automatically run pretest before it and posttest after it, if they exist in package.json.

vite.config.ts

export default defineConfig({
  run: {
    enablePrePostScripts: false, // Disable pre/post lifecycle hooks
  },
});

WARNING

This option can only be set in the workspace root's vite.config.ts. Setting it in a package's config will result in an error.

run.cache

• Type: boolean | { scripts?: boolean, tasks?: boolean }
• Default: { scripts: false, tasks: true }

Controls whether task results are cached and replayed on subsequent runs.

vite.config.ts

export default defineConfig({
  run: {
    cache: {
      scripts: true, // Cache package.json scripts (default: false)
      tasks: true, // Cache task definitions (default: true)
    },
  },
});

cache: true enables both task and script caching, cache: false disables both.

run.tasks

• Type: Record<string, Task | string | string[]>

Defines tasks that can be run with vp run <task>.

As a shorthand, a task value can be a command string or an array of command strings directly:

vite.config.ts

tasks: {
  build: 'vp build',
  check: ['vp lint', 'vp build'],
}

These are equivalent to setting only command on a task config:

vite.config.ts

tasks: {
  build: { command: 'vp build' },
  check: { command: ['vp lint', 'vp build'] },
}

Use the object form when a task needs other fields like cache, dependsOn, env, or input.

command

• Type: string | string[]

Defines the shell command to run for the task. The string is interpreted by a shell, so spaces, quoting, &&, pipes, and redirects all work as written on the command line.

vite.config.ts

tasks: {
  build: {
    command: 'vp build',
  },
}

An array runs each entry as its own command, sequentially, equivalent to joining them with &&. It is not a way to split one command into argv tokens — ['vp', 'build'] would try to run a command called vp with no arguments, then a command called build, instead of vp build.

vite.config.ts

tasks: {
  check: {
    // Two commands, run in order
    command: ['vp lint', 'vp build'],
  },
  bad: {
    // Wrong: this is NOT `vp build`; it is `vp` followed by `build`
    command: ['vp', 'build'],
  },
}

Each task defined in vite.config.ts must include its own command. You cannot define a task in both vite.config.ts and package.json with the same task name.

Commands joined with && (or supplied as an array) are automatically split into independently cached sub-tasks. See Compound Commands.

dependsOn

• Type: Array<string | { task: string, from: DependsOnFrom }>
• Default: []

DependsOnFrom accepts "dependencies", "devDependencies", "peerDependencies", or an array of those values.

Tasks that must complete successfully before this one starts.

vite.config.ts

tasks: {
  deploy: {
    command: 'deploy-script --prod',
    dependsOn: ['build', 'test'],
  },
}

Dependencies can reference tasks in other packages using the package#task format:

vite.config.ts

dependsOn: ['@my/core#build', '@my/utils#lint'];

Use the object form { task: string, from: DependsOnFrom } to reference tasks from all dependencies:

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 for details on how explicit and topological dependencies interact.

cache

• Type: boolean
• Default: true

Whether to cache this task's output. Set to false for tasks that should never be cached, like dev servers:

vite.config.ts

tasks: {
  dev: {
    command: 'vp dev',
    cache: false,
  },
}

env

• Type: string[]
• Default: []

Environment variables included in the cache fingerprint. When any listed variable's value changes, the cache is invalidated.

vite.config.ts

tasks: {
  build: {
    command: 'node build.mjs',
    env: ['NODE_ENV'],
  },
}

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. Do not add VITE_* or NODE_ENV here for a standard Vite build unless your project has extra build behavior Vite cannot report.

$ NODE_ENV=development vp run build    # first run
$ NODE_ENV=production vp run build     # cache miss: env 'NODE_ENV' changed

untrackedEnv

• Type: string[]
• Default: see below

Environment variables passed to the task process but not included in the cache fingerprint. Changing these values won't invalidate the cache.

vite.config.ts

tasks: {
  build: {
    command: 'node build.mjs',
    untrackedEnv: ['CI', 'GITHUB_ACTIONS'],
  },
}

untrackedEnv accepts the same wildcard and ! exclusion patterns as 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, 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
• CI/CD: CI, VERCEL_*, NEXT_*
• Terminal: Color variables (FORCE_COLOR, NO_COLOR, COLORTERM, TERM, TERM_PROGRAM) aren't passed to tasks unless you list them under env (the value gets fingerprinted, so changing it invalidates the cache) or untrackedEnv (passed without fingerprinting). If FORCE_COLOR isn't in either list, the child gets FORCE_COLOR=1 so cached logs stay colored. Colors get stripped on display when the terminal can't render them.

input

• Type: Array<string | { auto: boolean } | { pattern: string, base: "workspace" | "package" }>
• Default: [{ auto: true }] (auto-inferred)

Vite Task automatically detects which files are used by a command (see Automatic File Tracking). The input option can be used to explicitly include or exclude certain files.

Exclude files from automatic tracking:

vite.config.ts

tasks: {
  build: {
    command: 'vp build',
    // Use `{ auto: true }` to use automatic fingerprinting (default).
    input: [{ auto: true }, '!**/*.tsbuildinfo', '!dist/**'],
  },
}

Specify explicit files only without automatic tracking:

vite.config.ts

tasks: {
  build: {
    command: 'vp build',
    input: ['src/**/*.ts', 'vite.config.ts'],
  },
}

Resolve patterns relative to the workspace root using the object form:

vite.config.ts

tasks: {
  build: {
    command: 'vp build',
    input: [
      { auto: true },
      { pattern: 'shared-config/**', base: 'workspace' },
    ],
  },
}

The base field is required and controls how the glob pattern is resolved:

• "package": relative to the package directory
• "workspace": relative to the workspace root

Disable file tracking entirely and cache only on command/env changes:

vite.config.ts

tasks: {
  greet: {
    command: 'node greet.mjs',
    input: [],
  },
}

TIP

String glob patterns are resolved relative to the package directory by default. Use the object form with base: "workspace" to resolve relative to the workspace root.

output

• Type: Array<string | { auto: boolean } | { pattern: string, base: "workspace" | "package" }>
• Default: automatic write tracking

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.

vite.config.ts

tasks: {
  build: {
    command: 'node build.mjs',
    output: ['dist/**', '!dist/cache/**'],
  },
}

Use { auto: true } to keep automatic write tracking while adding explicit output globs:

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":

vite.config.ts

tasks: {
  build: {
    command: 'node build.mjs',
    output: [
      'dist/**',
      { pattern: 'shared-artifacts/**', base: 'workspace' },
    ],
  },
}

Set output: [] to disable output restoration for a cached task:

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
• Default: package root

Working directory for the task, relative to the package root.

vite.config.ts

tasks: {
  'test-e2e': {
    command: 'vp test',
    cwd: 'tests/e2e',
  },
}