DEV Community

Cover image for What goes into a key, and what comes back
VX
VX

Posted on Edited on Originally published at vznjs.github.io

What goes into a key, and what comes back

A cache is only as good as two lists: what goes into the key, and what
comes back on a hit. You write both down. vx checks each end.

diagram

What goes in

// packages/api/vx.config.ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    bundle: {
      exec: {
        command: 'vite build',
        env: { passThrough: ['NODE_ENV'] },
      },
      inputs: {
        files: ['src/**'], // required: this project's files
        env: ['NODE_ENV'], // values folded into the key
        runtime: ['bun --version'], // a command's output, folded in
        workspaceFiles: ['tsconfig.base.json'], // root files, by name
      },
      outputs: { files: ['dist/**'] },
      cache: true,
    },
  },
})
Enter fullscreen mode Exit fullscreen mode

files globs stay inside the project. A shared root file goes in
workspaceFiles by name. inputs.tasks picks which upstream tasks'
keys count.

A var in the key isn't the same as a var the task sees. List it in
both, as above. Change it and the key changes:

$ NODE_ENV=production vx run packages/api#bundle
bundling for production
└─ packages/api#bundle ── (6ms) success

$ NODE_ENV=production vx run packages/api#bundle
bundling for production
└─ packages/api#bundle ── (3ms) up-to-date

$ NODE_ENV=development vx run packages/api#bundle
bundling for development
└─ packages/api#bundle ── (5ms) success
Enter fullscreen mode Exit fullscreen mode

What comes back

A hit prints stdout and stderr in the order the task printed them, so a
warning shows where it did the first time:

$ vx run packages/api#bundle
┌─ packages/api#bundle > $ echo "bundling for $NODE_ENV"; echo "warn: large chunk" >&2; …
bundling for production
warn: large chunk
└─ packages/api#bundle ── (3ms) up-to-date
Enter fullscreen mode Exit fullscreen mode

If the outputs on disk already match, vx restores nothing. It checks a
few file stats and moves on. Delete one project's dist and only that
one comes back:

$ vx run build --all
  cache     local 4✓
  time      10ms

$ rm -rf packages/c/dist && vx run build --all
  cache     local 3✓ 1↓
  time      21ms
Enter fullscreen mode Exit fullscreen mode

Restores run on their own lane, so they never wait behind compilers.

A damaged download is a miss

Every archive vx uploads ends with a CRC-32 checksum and its own key.
Tar checks only its headers, and zstd can decode a flipped byte in an
image without error. So vx checks the sum first.

A wrong sum, wrong key, or a file outside the declared outputs turns the
hit into a miss, and the task runs.

Local hits are vx's own files, copied out unchecked (A cache hit is a
file copy
).

Uploads never hold the run

The local save is immediate. The upload runs in the background, and
dependents start at once. vx finishes uploads before it exits. A failed
upload is a warning, never a red build.

One-project workspace for bundle, four-project demo for build · vx dbe4033 · 2026-10-23

The full rules are in Caching and the
schema. More at
vznjs.github.io/vx.


Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

Top comments (0)