Quickstart

Cache your first task in two minutes, in a workspace you already have.

What you need

Git, and macOS or Linux with glibc (not Alpine’s musl). On Windows, use WSL2.

1. Set up vx

   Run this at the root of your workspace, inside a git checkout:

   bunx @vzn/vx init

   init installs vx, writes an empty vx.config.ts at the root, and declares your lockfile’s plugin (bun() beside bun.lock) in .vx/workspace.ts.

2. Add a task

   Give vx.config.ts a build task: the tool it runs, the files it reads, and the files it writes. vx runs the tool itself, with no package script in between.

   vx.config.ts

   import type { ProjectConfig } from '@vzn/vx/config'
   
   export default {
     tasks: {
       build: {
         exec: { command: 'tsc' },
         inputs: { files: ['src/**', 'tsconfig.json'] },
         outputs: { files: ['dist/**'] },
         cache: true,
       },
     },
   } satisfies ProjectConfig

   In a monorepo, give each package its own vx.config.ts beside its package.json, and add dependsOn: ['^build'] to build a package’s dependencies first.

   At the root, vx run build --all runs every package’s build.

   Then save the change for every run to read:

   vx lock

   Commit .vx/ and each vx.lock.json it writes beside a config: runs read the lock, and a reviewer reads a config’s tasks in its vx.lock.json. vx show lists every project the lock holds.

3. Run it twice

   vx run build
   vx run build

   The first run builds and stores the result. The second finds nothing changed and skips the work (up-to-date). my-app is the name in your package.json:

   second run

   ┌─ my-app#build > $ tsc
   └─ my-app#build ── (3ms) up-to-date

4. Change a file and ask why

   Edit a file in src/, run again, and ask vx what changed. verdict names the file you edited:

   vx run build
   vx why build

     Why my-app#build
     run       01a1a6e5-f341-73e6-9beb-422ab5657b82
     this run  2026-11-04T14:10:50.333Z · success · executed · key e5165ba21c5d5286
     previous  2026-11-04T14:10:50.163Z · cache-hit · up-to-date · key 1d1cb0c5a5a357f3
     verdict   cache key changed: file src/index.ts
   
     What changed 1 of 6
     change   kind  name          before → after
     changed  file  src/index.ts  d00491fd7e5bb6fa28c517a0bb32b8b506539d4d → 0cfbf08886fca9a91cb753ec8734c84fcbe52c9f
   
     What to do
     file      an edit re-runs by design; a file the task does not read belongs out of inputs.files

Next

Configure tasksInputs, outputs, dependencies and environment.

Run on CIGitHub Actions, then a remote cache and many runners.

Coming from Turborepo or NxKeep your config, or convert it.

Something looks wrongEvery message vx prints, and its fix.