DEV Community: VX

Flags you already know

VX — Fri, 09 Oct 2026 16:43:39 +0000

Years of turbo run and nx run-many live in your fingers. vx does not
ask you to forget them on day one. Every flag either works, is rewritten,
or is answered with the command that does it here.

Works as is

-t, -p, --exclude and Nx's --skip-nx-cache mean what you expect:

$ vx run build --all --skip-nx-cache --dry
would run:
  ▶  @demo/api#build   cache miss — would exec   32b3a0bf  ~326ms
  ▶  @demo/docs#build  cache miss — would exec   1f858edb  ~311ms
  ▶  @demo/ui#build    cache miss — would exec   46046abb  ~313ms
  ▶  @demo/web#build   cache miss — would exec   b25e5bf4  ~310ms

4 task(s) planned, 4 would run.

Answered with the vx way

A flag vx has no use for is never ignored. It is refused with the
spelling that does the job:

$ vx run build --parallel
vx run: --parallel (turbo): vx always honours `dependsOn`; `--concurrency <n>` sets how many run at once (see `vx run --help`)

Nx's verbs and project:target get the same treatment:

$ vx run web:build
vx run: `web:build` is Nx's project:target: vx run @demo/web#build

$ vx run-many -t build
`nx run-many` is `vx run <task> --all` here; -t, -p, --exclude and --parallel work as they are

$ vx affected -t test
`nx affected` is `vx run <task> --affected` here; -t, --base and --exclude work as they are

$ vx graph
`nx graph` is `vx run <task> --graph[=<file>.dot]` here: the task graph as Graphviz DOT

One table, held by a test

Every row lives in one table, rendered into the CLI reference, and a
test drives each row, so the docs and the binary cannot disagree.

Learn more: Turbo and Nx flags and
Flags you already know.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

Your run, on the pull request

VX — Fri, 09 Oct 2026 16:39:42 +0000

A red CI job should not mean scrolling a log. @vzn/vx-ci writes each
vx run where you already look on GitHub.

import { defineWorkspace } from '@vzn/vx/config'
import { github } from '@vzn/vx-ci'

export default defineWorkspace({
  plugins: [github()],
})

That is the whole setup. Off GitHub Actions the plugin declines and
costs nothing, so the line stays on for laptops too.

The job summary

Every run appends a block to the workflow's summary page: the verdict,
the counts, the failures first, then every task. This is the markdown
the plugin wrote for a run where one test failed:

## ❌ vx run

**8** tasks · **6** executed · **2** cache hits (2 up-to-date, 0 restored) · **1** failed · 901ms

### Failures

- **@demo/ui#test** — exit 1

Below that sits a row per task with its status and time, and a footer
naming the vx version and the command.

A task killed by a signal reads exit 137 (128 + SIGKILL), a timeout
reads timed out, exit 143, and each failure names the tasks it
blocked.

A check on the commit

With GITHUB_TOKEN in the job, the plugin also posts a check run
(named vx unless you pass checkName) whose output is that same
summary, so the result sits next to the commit and the pull request.

A cache a pull request cannot poison

On Actions the plugin sets the cache scope from the ref. A push to the
default branch reads and writes the trusted keys. A pull request becomes
pr-<n>: it reads its own keys, then main's, and writes only its own. So
a branch never writes what main reads. Set cacheScope: false to opt
out, or set cacheScope in vx.workspace.ts yourself.

It never breaks the build

The summary is written by a telemetry sink. vx isolates sinks and bounds
their flush, so a slow or failing GitHub write can never fail or stall
the run.

Learn more: CI and remote and
Results on GitHub.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

A run you can read

VX — Fri, 09 Oct 2026 16:34:09 +0000

Eight tasks in four projects, run in parallel, used to mean eight logs
cut into each other. vx prints a run in three parts, and each part has
one job.

A line per task

While the run works, each task gets one line: its glyph, its time, its
outcome and whether the cache had it.

$ vx run test --all
 ⏺︎   310ms success miss     @demo/ui#build
 ◼︎     3ms failed  miss     @demo/ui#test
 ⏺︎   308ms success miss     @demo/docs#build
 ⏺︎   310ms success miss     @demo/web#build
 ⏺︎   207ms success miss     @demo/docs#test
 ⏺︎   207ms success miss     @demo/web#test

A frame for what failed

A failed task's log comes back whole, in its own frame, with the command
that ran. No other task's output is woven into it.

┌─ @demo/ui#test > failed (exit 1)

$ echo "expected 2, got 3" && exit 1

├─ OUTPUT ──────────────────────────────────────────────────

expected 2, got 3

└─ @demo/ui#test ── (3ms) failed (exit 1)

Ask for every log with --output-logs full: each task still gets its
own frame, in the order tasks finish.

One summary, last

─ vx 0.0.0 ───────────────────────────────────────────────────
  projects  ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            4 in run · 4 total
  tasks     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            8 success · 8 total
  cache     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            8 up-to-date

  info      4 workers · local cache
  time      23ms
  result    8 tasks · all cached · 2.12s saved · 23ms

That is the same eight tasks a second time, all cached: 23 ms, and the
summary says how much work the cache saved.

The summary is the last thing on screen, so the answer to "did it pass?"
is always where your eyes land. On CI the frames fold into log groups,
and vx last replays the summary later.

Learn more: Framed output
and Run summary.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

The last run, on request

VX — Fri, 09 Oct 2026 16:28:37 +0000

The terminal scrolled away, CI printed ten thousand lines, or an agent
ran the build an hour ago. vx keeps a record of every run, so the
question "what happened?" has an answer after the fact.

vx last

The last run

$ vx last
run 01a11e14-87de-749d-a6ba-eca7bb441469 — ok
  $ vx run build --all
  2026-10-09T00:33:44.415Z · 62ms · master @ 64a144f9
  4 tasks · 4 hits (1 up-to-date, 3 restored: 3 local, 0 remote)

  restored-local    @demo/ui#build        31ms  46046abb75e9c084
  restored-local    @demo/web#build       31ms  b25e5bf41cb7a54d
  restored-local    @demo/docs#build      31ms  1f858edb724ca91b
  up-to-date        @demo/api#build        9ms  32b3a0bfa973a7a8

The command, the branch and commit, the time, and every task with its
outcome and cache key.

The run that broke

--failed skips to the newest run that failed, and ends with the
command that runs only what failed:

$ vx last --failed
run 01a11dab-5561-75fe-aa33-fd0fa220ad42 — FAILED
  $ vx run test --all
  2026-10-08T22:38:50.209Z · 606ms · feat @ 5f0b0da6+dirty
  8 tasks · 2 hits (2 up-to-date, 0 restored) · 1 failed

  failed (exit 1)   @demo/ui#test          4ms  fb349347b8a40aeb  0.5× cpu
  success           @demo/web#test       206ms  9b78e7e1a95c53db  0.0× cpu
  success           @demo/docs#test      205ms  36a0120a08d6c9d9  0.0× cpu
  ...

  re-run what failed: vx run @demo/ui#test

Recent runs

$ vx last --list
ok     2026-10-09T00:33:44.415Z  01a11e14-87de  4 tasks · 4 hits (1 up-to-date, 3 restored: 3 local, 0 remote)   62ms  $ vx run build --all
FAILED 2026-10-08T22:38:50.209Z  01a11dab-5561  8 tasks · 2 hits (2 up-to-date, 0 restored) · 1 failed          606ms  $ vx run test --all
ok     2026-10-08T22:38:41.669Z  01a11dab-3405  8 tasks · 2 hits (2 up-to-date, 0 restored)                     912ms  $ vx run test --all

One task's output

$ vx last --log app#test
FAIL src/sum.test.ts > adds
  expected 4, received 5

--log prints what one task printed in the last run that ran it. A
failure's output is kept, and a cached task's log is its cache entry,
so a task that passed reads too. Agents get the same through
vx mcp's getTaskLog.

The record lives in the workspace's cache database, so it costs the run
nothing it was not already writing. --format json gives agents the
same answer as data.

Learn more: the CLI reference and
vx last.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

See what a task really is

VX — Fri, 09 Oct 2026 16:23:05 +0000

A vx.config.ts is TypeScript. Presets compose, plugins add tasks, a
function can compute a command. So the file is not always the answer to
"what will this task do?". vx show is.

vx show @demo/web#build

Every project, one line each

$ vx show
@demo/api   packages/api   2 tasks
@demo/docs  packages/docs  2 tasks
@demo/ui    packages/ui    2 tasks
@demo/web   packages/web   2 tasks

One task, resolved

$ vx show @demo/web#build
@demo/web — packages/web

build
  command:       mkdir -p dist && sleep 0.3 && cp src/index.ts dist/index.js
  dependsOn:     ^build
  inputs.files:  src/**
  outputs.files: dist/**

This is the config the cache key sees, not the source text. When a
preset sets outputs or a plugin rewrites a command, it shows here.

The same answer, for agents

--format json prints the object itself, so a script or an agent reads
the task without parsing text:

$ vx show @demo/web#build --format json
{
  "name": "@demo/web",
  "dir": "packages/web",
  "task": "build",
  "config": {
    "exec": { "command": "mkdir -p dist && sleep 0.3 && cp src/index.ts dist/index.js" },
    "dependsOn": ["^build"],
    "cache": {
      "inputs": { "files": ["src/**"] },
      "outputs": { "files": ["dist/**"] }
    }
  }
}

vx show --affected lists the projects a change reaches, without
running anything.

Learn more: the CLI reference and
vx show.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

See the plan before you run it

VX — Fri, 09 Oct 2026 16:17:32 +0000

Before a long run, you want to know what it will do. --dry answers
without running anything: every task in the graph, whether the cache
would answer it, its key, and how long it took last time.

$ vx run test --all --dry
would run:
  ▶  @demo/api#test    cache miss — would exec   62269624  ~213ms
  ▶  @demo/api#build   cache miss — would exec   10361de3  ~326ms
  ◉  @demo/docs#test   cache hit (local)         067839a7
  ◉  @demo/docs#build  cache hit (local)         b5134b6e
  ◉  @demo/ui#build    cache hit (local)         6a36fb4c
  ◉  @demo/ui#test     cache hit (local)         d5097182
  ◉  @demo/web#test    cache hit (local)         a5787dc7
  ◉  @demo/web#build   cache hit (local)         731116aa

8 task(s) planned, 6 cache hits (6 local), 2 would run.
predicted: ~539ms wall · ~539ms total execution

One edit to api: two tasks would run, six come from the cache.

Real keys, real predictions

A dry run derives the same keys a real run would and asks the same
cache. A "hit" in the plan is a hit in the run. The time next to each
task is what it took the last time it ran. The wall prediction lays
those times on the graph: api#test waits for api#build, so the two
run one after the other, ~539 ms.

For scripts and agents

--dry=json prints the same plan as JSON: tasks, keys, hit or miss,
predicted times. An agent can decide whether a run is worth starting,
or show a reviewer what a change will rebuild.

vx run build --affected --dry=json

The graph itself

--graph writes the task graph as Graphviz DOT, to stdout or a file:

vx run build --all --graph=graph.dot
dot -Tsvg graph.dot > graph.svg

Learn more: Plan before you run and
the CLI reference.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

Run only what a change reaches

VX — Fri, 09 Oct 2026 16:11:59 +0000

A pull request that touches one library should not test forty apps.
--affected runs a task only in the projects a change reaches: the ones
whose files changed, and every project that depends on them.

vx run test --affected

What it picks

Four packages. The branch edits ui. web and docs depend on ui;
api depends on nothing.

Ask for the plan first. --dry prints it and runs nothing:

$ vx run test --affected=master --dry
would run:
  ▶  @demo/docs#test   cache miss — would exec   067839a7  ~216ms
  ▶  @demo/docs#build  cache miss — would exec   b5134b6e  ~313ms
  ▶  @demo/ui#build    cache miss — would exec   6a36fb4c  ~320ms
  ▶  @demo/ui#test     cache miss — would exec   d5097182  ~209ms
  ▶  @demo/web#test    cache miss — would exec   a5787dc7  ~216ms
  ▶  @demo/web#build   cache miss — would exec   731116aa  ~311ms

6 task(s) planned, 6 would run.

api is not in it. The run shows the same set, three of four projects:

$ vx run test --affected=master
 ⏺︎   313ms success miss     @demo/ui#build
 ⏺︎   205ms success miss     @demo/ui#test
 ⏺︎   309ms success miss     @demo/web#build
 ⏺︎   311ms success miss     @demo/docs#build
 ⏺︎   204ms success miss     @demo/web#test
 ⏺︎   205ms success miss     @demo/docs#test

─ vx 0.0.0 ───────────────────────────────────────────
  projects  3 in run · 4 total
  tasks     6 success · 6 total

Which base

--affected compares against a git base. Name one (--affected=main),
or let vx pick: the workspace's affectedBase, else origin/HEAD, else
main or master, else HEAD~1. On a pull request, set
affectedBase once in vx.workspace.ts and every run agrees.

It is sugar for a filter, --filter "...[<base>]": the projects changed
since the base, and their dependents. So it combines with any other
filter, and vx show --affected lists the projects without running.

Why the cache still matters

--affected decides which projects are in the run. The cache key still
decides which tasks execute. A file outside every task's inputs, a
README say, puts its project in the set, and every task there is a hit.

The edges are task edges

vx follows the task graph, not only package.json. A task that reads
another project's output through dependsOn is downstream of it, even
without a package dependency. So the set is what your tasks really
depend on.

Learn more: the CLI reference and
Filters.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

Observability that cannot break a run

VX — Fri, 09 Oct 2026 16:00:51 +0000

Every build tool eventually grows an integration point for "tell
someone what happened": Sentry, Slack, a metrics endpoint, an
OpenTelemetry collector. Every one of those integrations is also a way
for a network hiccup to fail a build, and the usual defence is a
policy: please catch your errors, please do not block.

vx's telemetry capability makes it a structure instead.

The contract

interface TelemetrySink {
  readonly name?: string
  readonly wants?: ReadonlyArray<'run.start' | 'task.start' | 'task.end' | 'task.log' | 'task.sample' | 'run.end'>
  onRecord?(record: TelemetryRecord): void          // must return promptly; buffer here
  onRunSummary?(summary: RunSummaryRecord): void    // one per run, at the end
  flush?(signal: AbortSignal): Promise<void>        // awaited at end of run, time-bounded;
                                                    // `signal` aborts at the deadline
}

A sink is handed plain-data records and a read-only context: the
workspace root, the cache directory, a warn function. No event bus,
no cache handle, no run request. There is no method on anything it
receives that reaches scheduling, caching or execution. The guarantee
that a sink cannot change a build is not a rule sinks follow; it is the
absence of a path.

Crash isolation

If a sink throws, from onRecord, onRunSummary or flush, it is disabled for the rest of the run and a warning is printed. Other sinks keep receiving records. The run's outcome is unaffected.
onRecord must return promptly, so the contract says buffer and do not await. flush() is the one awaited drain point, at the end of the run. All sinks flush at once under one shared bound, three seconds by default (VX_TEARDOWN_TIMEOUT_MS overrides it), so a wedged collector cannot hold the process's exit hostage.
A sink that lists what it wants costs the source nothing for the kinds it skips; the large task.log stream is off unless asked for.

The other direction is isolated too. A plugin whose setup() throws
aborts the run before any work starts, naming the plugin, because a
broken plugin should fail loudly and early rather than silently
degrade. An executor or cache factory that throws aborts the same
way; those are load-bearing.

Zero cost when absent

The design has a second property that matters as much as safety: no
telemetry plugin means no telemetry cost. No bus subscriber is
registered, no run summary is assembled, no git is spawned for
provenance. A workspace with no sinks pays nothing for the capability
existing. That is the general rule for every seam in vx: a stage nobody
fills is not a no-op call, it is no call.

What is built on it

@vzn/vx-otel maps each run to OTLP traces, metrics and logs over HTTP/JSON with no OpenTelemetry SDK dependency. The wire format is small and the SDK is not. Each task's span is sent as the task ends, so a dashboard follows a CI run while it runs; no send ever holds a task.
@vzn/vx-ci writes every run as a GitHub Actions job summary and, given a token, a completed check run on the built commit, so a red run explains itself in the pull request's checks list.
Anything else is a few dozen lines: buffer records in onRecord, post them in flush. The guide has a runnable sink against the exported types.

The same rule for remote caches

The never-fail discipline is not only for telemetry. A remote cache
layer that errors, times out or is unreachable degrades to a miss on
that layer, the lookup continues down the chain to the local cache,
and the run completes. Every remote path (get, put, ingest, prefetch)
is wrapped the same way; a remote outage is a slower run, never a
broken one, and a plugin that never fails still warns so you know it
happened.

The guide is Writing a vx plugin.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

Remote execution without moving the scheduler

VX — Fri, 09 Oct 2026 15:55:19 +0000

Distributed builds usually arrive as a platform: a service that owns
the graph, agents that run it, a dashboard that shows it. vx's version
is a plugin that fills two seams, executor and cache, against a
wire that already exists: Bazel's Remote Execution API, spoken by
NativeLink, BuildBuddy, Buildbarn and bazel-remote.

// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  plugins: [
    reapi({
      endpoint: 'grpcs://cache.example.com:443',
      execute: true,
      platform: { OSFamily: 'Linux', 'container-image': 'docker://node:22' },
      capacity: 64,
    }),
  ],
})

Execution is off unless execute: true is set, even with the plugin
declared for caching. Changing where a build runs is not something a
plugin should do by being present.

The scheduler never leaves

vx owns the task graph and decides placement once per task, before
scheduling. Telemetry, retries, timeouts, the cache and the logger
behave exactly as they do locally, because none of them moved. The
executor's job is one function: run this command with these inputs and
give me the outputs. capacity gives it its own scheduler pool, so a
64-wide fleet is not throttled by a laptop's core count and remote
tasks reserve none of the local CPU budget.

vx run --dry prints the decision per line: @vx/reapi, @local or
@noop.

What goes remote

Only cacheable tasks. A task with no cache block has no declared inputs, so a worker would run it against an empty tree.
Not persistent tasks, or anything depending on one. A worker cannot reach a port on your machine; the placement stage knows.
Not sandboxed tasks, or anything depending on one. The sandbox is local machinery a worker does not have, and a boundary verified remotely would pass vacuously.
Not exec.remote: false, or anything depending on it. A task that talks to Docker, a device or a local daemon is pinned by one field.
Not a task whose key folds a runtime probe (cache.inputs.runtime, workspaceRuntime): the key holds this machine's node -v, which a worker cannot prove it shares. Its dependants may still go.

A task's inputs on the worker are exactly what its cache key declares:
cache.inputs.files, resolved env values, upstream outputs. Ambient
state such as an undeclared tsconfig.json, .npmrc or
node_modules is not in the key and therefore not on the worker. The
sandbox is how you find the gap before you mark a
task remote-eligible: a task that passes locally with the declared
paths as its only reads will pass on a worker.

`node_modules`: install as an action

Workers are stateless and node_modules is ambient. The answer is an
explicit install task pinned to the pool with exec.remote: 'only':

install: {
  exec: { command: 'pnpm install --frozen-lockfile', remote: 'only' },
  cache: {
    inputs: { files: ['package.json', 'pnpm-lock.yaml'] },
    outputs: { files: ['node_modules/**'] },
  },
},
build: {
  dependsOn: ['install'],
  exec: { command: 'tsc -p .' },
  cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
},

Verified end to end against a live NativeLink pool: install runs on a
worker, once per lockfile change, and its outputs never touch your
disk. A dependent's input tree references the install outputs in the
remote content-addressed store, so the bytes flow worker to store to
worker without transiting your machine. With no remote executor
declared, install is a local no-op and dependents use whatever your
machine has, so a laptop run behaves as it did before the field
existed.

One artifact format, both directions

The same tar.zst bytes serve the local cache and the remote's
action cache. Nothing is repacked at the boundary. A remote error, a
timeout, an unreachable endpoint all degrade to a miss on that layer
and the run continues locally; a cache-only server that advertises no
execution capability declines the executor with a warning and keeps
serving the cache.

None of this is in core. Core has the two seams and the placement
stage; @vzn/vx-reapi is the proof they are wide enough. The guide,
including worker image requirements and how output globs travel over a
wire that has no globs, is Remote
execution.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

Flaky is a claim only declared inputs can back

VX — Fri, 09 Oct 2026 15:49:46 +0000

Flaky-test detection is one of the features that usually lives behind
a cloud login. Nx sells it. It is also one of the easiest things to get
wrong, because "flaky" is used to mean "failed and I do not want to
look," and a tool that agrees with that use is teaching a team to
ignore red.

vx defines it narrowly, and the narrow definition is the feature.

The definition

A task is flaky when one of two things is on record:

its exact cache key failed after it had passed, this run included (a cache hit counts as a pass; it replayed one), or
it needed a retry this run (exec.retries or --retry) and then passed.

A failure on a key that never passed is a break. The inputs
changed and the result is red, which is what a red run usually means,
and it is not listed. Nor is the first pass after only failures: that
is a recovery (a missing tool installed), not a flake. Only tasks with a cache block are judged at
all: "same inputs, different outcome" is a claim only declared inputs
can back. A task without them is keyed on its config alone, and two
runs of it are not the same inputs in any meaningful sense.

What you see

A flaky task says so on its own row in the run's task list, in a dim
note after its name:

 ◼︎   4.21s failed  miss     app#test flaky - passed 3× before
 ⏺︎  12.84s success miss     api#e2e flaky - failed 1× before · 2 attempts

A task that was not flaky carries no note. vx info keeps the
standing list across runs, --summarize carries it as typed data
(flaky: { passes, failures, attempts } on the task, so a consumer can
tell a break from a flake without parsing text), and the MCP server
reports the same signal to an agent — getRunHistory as each task's
failure mode, getWorkspaceInfo as the standing list — so an agent
does not learn to shrug at a repeated failure on changing inputs.

Why it is free

The information was already there. Every cache entry records its key,
its outcome and its run. Asking "has this key ever had the other
outcome" is one probe of the failed-row index on a green miss, and
nothing at all on a run that executed nothing. There is no upload
because there is nothing to upload to; the history is the local
cache.db that vx why and vx last already read.

That is also why it works on the first day. A service-side detector
needs a fleet of runs before it can say anything. vx's needs the second
run of the same key on your machine.

What it is not

It is not a retry policy. exec.retries is separate and explicit, and
a task that passes on retry is reported as flaky rather than quietly
made green. It is not a quarantine: nothing is skipped, ever, because a
skip is a silent pass. It is a label on a fact, kept where you can act
on it, and the act is yours.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

A lockfile bump should re-key two tasks, not sixty

VX — Fri, 09 Oct 2026 15:44:14 +0000

Out of the box, vx folds the whole lockfile into the workspace
fingerprint (Turborepo keys each package on the lockfile changes that
reach it), and the workspace fingerprint is in
every task's key. That is coarse but correct. Any pnpm install that
changes pnpm-lock.yaml invalidates every cached task, and --affected
selects every project.

It is also the single largest source of "why did everything rebuild"
in a large workspace. A patch bump to a test utility used by one
package re-runs the builds of all of them.

Key each project on what it can reach

@vzn/vx-lockfile ships one plugin per package manager: pnpm(),
bun(), npm(), yarn(). Each claims its lockfile out of the
workspace fingerprint through the fingerprint seam and instead
contributes, per task, a digest of its project's resolved dependency
closure:

// vx.workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { pnpm } from '@vzn/vx-lockfile'

export default defineWorkspace({ plugins: [pnpm()] })

Nothing else changes. vx why names the material as
plugin @vzn/vx-lockfile/pnpm, and the workspace fingerprint line
stops moving when the lockfile is edited.

The closure is exactly what the project's node_modules can resolve:

its dependencies, devDependencies and optionalDependencies, transitively through the lockfile's own resolution graph;
each package by name, version and resolved peers, because foo@1(react@18) and foo@1(react@19) are different directories on disk, plus its integrity and any patch applied to it;
a link: or workspace: dependency folds the linked workspace package's whole reach, since what A can import through B is B's closure;
install-wide material every project folds: the lockfile version and fields such as pnpm's settings. Under pnpm() and bun(), overrides, catalogs and patches count only where they reach.
the root package's own closure, folded into every project (added 2026-09-24): the root's tools run from the root node_modules/.bin on every task's PATH, so a root devDependency bump that re-keyed nothing replayed the old tool's output.

bun() does the same through Bun's hoisted layout (a nested version
counts for the package it is nested under and no other); npm()
through package-lock.json's packages map; yarn() per workspace
through berry's descriptors. Yarn classic records no workspaces, so
every project folds one root digest, which is coarse and honest about
what that file contains.

A phantom dependency, imported but never declared, is in no closure.
Declare it.

`--affected` follows the same claim

The plugin's affected(change) hook answers the selection question
too. vx run test --affected with a lockfile diff selects the projects
whose closure the diff reaches, not every project. The rule that keys a
task and the rule that selects it are one rule, so they cannot drift.

Measured in the repository that ships it

vx's own repository declares bun(). Measured 2026-10-08 with
vx run ci --all --dry=json before and after a version bump in
bun.lock: bumping astro, which only the docs site reaches, re-keys
that site's 6 tasks of the gate's 57; without the plugin, all 57
re-key.

The root's closure is in every key, and this repository's root links
seven of its packages as devDependencies, so bumping protobufjs
(reached through @vzn/vx-reapi) re-keys every task either way. A
dependency change costs what the dependency change touches, and the
root touches every task.

The plugin is separate from core on purpose. Core owns the fingerprint
seam, the memo and the per-run gate; the lockfile parsers are
package-manager knowledge, and package-manager knowledge changes on the
package manager's schedule. The guide is
Configure › Lockfiles.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

vx lock: freezing what the key sees

VX — Fri, 09 Oct 2026 15:38:41 +0000

A TypeScript config buys composition and costs one guarantee: what it
evaluates to can depend on where it is evaluated. process.env.CI,
a Date, an import that resolved differently on another machine. On a
laptop that is fine. In a pipeline that must run exactly the config a
reviewer approved, it is a hole.

vx lock closes it the way package managers closed the same hole for
dependencies.

Three verbs

vx lock              # evaluate every vx.config.* now; write vx-lock.json
vx lock --check      # audit: hashes + full re-evaluation against the lock; exit 1 on drift
vx run … --frozen    # consume the lock; no evaluation at all

vx lock evaluates each config in the current environment and stores
the post-evaluation object plus a content hash of the config file.
Plain runs always evaluate live; the lock's existence changes
nothing about vx run. Only --frozen consumes it, and under
--frozen there is no evaluation and no staleness check of its own: a
config's env reads keep their lock-time values, a project absent from
the lock is a hard error, a missing lock is a hard error.

The check that a hash cannot do

--check does two things, and the second is the reason the verb
exists. It compares the stored content hash of each config file, which
catches an edit. Then it re-evaluates every config in the current
environment and compares the result to the frozen object, which
catches what an edit-detector cannot: an env value read at evaluation
time that differs from the lock's, an imported preset that changed, a
computed command whose input moved. Every mismatched project is listed
on stderr and the exit code is 1.

The CI recipe is two lines:

vx lock --check && vx run ci --all --frozen

The first line proves the lock still describes the configs as this
machine would evaluate them. The second runs exactly the lock. A pull
request that changes a config without re-running vx lock fails the
first line, which is the point.

What the lock is not

Not a cache key input. vx-lock.json is excluded from every task's input set and from the workspace fingerprint, so running vx lock does not re-key the workspace.
Not a substitute for cache.inputs.env. The lock freezes what a config evaluated to. An env var a task reads at run time is still a run-time input and belongs under cache.inputs.env, where it joins the key. The two mechanisms are parallel on purpose: config-time values are locked, run-time values are keyed.
Not a performance feature. Evaluation is already cheap and cached where it is provably pure. --frozen is about determinism, and the milliseconds it saves are incidental.

For agents

An agent asks the same question in JSON: vx lock --check --format json
prints {"upToDate": false, "audited": 4, "notAudited": 0, "problems": [...]}
with the same exit code, and vx mcp answers it as checkLock. Each
problem is the line a person would read on stderr.

Where it came from

The lock exists because the resolved-config hash made configs
powerful, and power needs an audit. Package managers learned the same
lesson with --frozen-lockfile: let resolution be dynamic in
development and pin it where reproducibility is the contract. The
design note is in the repository under docs/design/config-lock; the
reference is vx lock.

Originally published on the vx blog. vx is an MIT task runner and build cache for JS monorepos: github.com/vznjs/vx.

Written with AI assistance.

DEV Community: VX

Flags you already know

Works as is

Answered with the vx way

One table, held by a test

Your run, on the pull request

The job summary

A check on the commit

A cache a pull request cannot poison

It never breaks the build

A run you can read

A line per task

A frame for what failed

One summary, last

The last run, on request

The last run

The run that broke

Recent runs

One task's output

See what a task really is

Every project, one line each

One task, resolved

The same answer, for agents

See the plan before you run it

Real keys, real predictions

For scripts and agents

The graph itself

Run only what a change reaches

What it picks

Which base

Why the cache still matters

The edges are task edges

Observability that cannot break a run

The contract

Crash isolation

Zero cost when absent

What is built on it

The same rule for remote caches

Remote execution without moving the scheduler

The scheduler never leaves

What goes remote

node_modules: install as an action

One artifact format, both directions

Flaky is a claim only declared inputs can back

The definition

What you see

Why it is free

What it is not

A lockfile bump should re-key two tasks, not sixty

Key each project on what it can reach

--affected follows the same claim

Measured in the repository that ships it

vx lock: freezing what the key sees

Three verbs

The check that a hash cannot do

What the lock is not

For agents

Where it came from

`node_modules`: install as an action

`--affected` follows the same claim