Upgrading to 1.0
Before 1.0 a release may break what the last one did. Each heading below
is a breaking commit (type!: or a BREAKING CHANGE: footer), newest
first; its text is that footer: what changed and what to do.
cache: one entry_inputs row per entry, not per component
Section titled “cache: one entry_inputs row per entry, not per component”SCHEMA_VERSION v34. The first run drops the local index once; artifact files stay and are re-adopted on their next hit.
cache: store small artifacts inline in the store index
Section titled “cache: store small artifacts inline in the store index”SCHEMA_VERSION v33. The first run drops the local index once; artifact files stay and are re-adopted on their next hit.
vx-reapi: connect a bare endpoint with TLS, as Bazel does
Section titled “vx-reapi: connect a bare endpoint with TLS, as Bazel does”a vx-reapi endpoint with no scheme now uses TLS; a plaintext server needs grpc:// or tls: false.
cache: replay stderr on cache hits
Section titled “cache: replay stderr on cache hits”every cached task misses once after upgrading to vx-cache-v42.
cache: drop unread store fields, fix chunking comments
Section titled “cache: drop unread store fields, fix chunking comments”Cache.storeFallback and Cache.storeMoved are removed; nothing read them.
cache: clean through an in-project output link, bump to v41
Section titled “cache: clean through an in-project output link, bump to v41”every cached task misses once after upgrading to vx-cache-v41.
workspace: refuse env names sh would drop
Section titled “workspace: refuse env names sh would drop”exec.env define and passThrough names must be shell identifiers ([A-Za-z_][A-Za-z0-9_]*); other names are refused at load.
config: accept readonly lists in every config array field
Section titled “config: accept readonly lists in every config array field”config array fields are typed readonly; code that mutates a resolved config list must copy it first.
workspace: refuse a tag that —filter tag: cannot name
Section titled “workspace: refuse a tag that —filter tag: cannot name”a tag that —filter tag: cannot select (**, an upper-case glob such as A*) is now refused at config load.
cache: dry prune on an earlier index previews the store
Section titled “cache: dry prune on an earlier index previews the store”Cache.orphansBeforeReset is gone; open a Cache in ‘preview’ mode instead.
cache: bump CACHE_VERSION to vx-cache-v40
Section titled “cache: bump CACHE_VERSION to vx-cache-v40”every cached task misses once after the upgrade.
vx-ci: rename @vzn/vx-github to @vzn/vx-ci
Section titled “vx-ci: rename @vzn/vx-github to @vzn/vx-ci”import github() from ‘@vzn/vx-ci’ instead of ‘@vzn/vx-github’.
cache: keep artifacts when the store schema changes
Section titled “cache: keep artifacts when the store schema changes”Cache.getMany and CacheLayer.getMany take an optional per-hash get context; a layer that ignores it is unchanged.
cache: share cache entries across workspaces
Section titled “cache: share cache entries across workspaces”SCHEMA_VERSION v32; existing entries miss once.
cache: count restored and up-to-date hits everywhere
Section titled “cache: count restored and up-to-date hits everywhere”SCHEMA_VERSION v30 -> v31; an older index is dropped on first open and its artifacts are left for vx cache prune. WhyDidThisRerun’s thisRun / previousRun, RunSummaryRow, InvocationDetail, RunSummaryRecord and CacheStats gain fields.
orchestrator: drop the end-of-run failure recap
Section titled “orchestrator: drop the end-of-run failure recap”src/orchestrator/failure-recap.ts leaves the package, with formatFailureRecap and DefaultLogger.failureRecap.
cache: key the blob-size verdict by the index file’s hash
Section titled “cache: key the blob-size verdict by the index file’s hash”SCHEMA_VERSION v29 -> v30; an older index is dropped on first open and its artifacts are left for vx cache prune.
vx-migrate: run every Nx executor through nx-exec
Section titled “vx-migrate: run every Nx executor through nx-exec”a migrated config writes nx-exec lines where it wrote jest, vite, tsc, node and other executor commands.
workspace: keep existing configs in vx init, write the rest
Section titled “workspace: keep existing configs in vx init, write the rest”vx init where configs already exist exits 0 (kept) instead of 1 (refused).
vx-reapi: inline the wire-only keys
Section titled “vx-reapi: inline the wire-only keys”@vzn/vx-reapi’s plugin-api record no longer lists the WireOnly type (it was never exported; ReapiPluginOptions is unchanged in shape).
vx-reapi: refuse the wire-form options reapi() ignored
Section titled “vx-reapi: refuse the wire-form options reapi() ignored”reapi() no longer accepts onWarn, tlsCaPem, tlsClientCertPem or tlsClientKeyPem; use tlsCertificate, tlsClientCertificate and tlsClientKey (PEM files).
vx-reapi: stop exporting the wire and Merkle internals
Section titled “vx-reapi: stop exporting the wire and Merkle internals”@vzn/vx-reapi no longer exports ReapiClient, reapiExecutor, acceptsTask, globToOutputPath, outputPathSets, buildInputTree, canDigest, decodeDirectory, decodeTree, digestWith, encodeAction, encodeCommand, encodeDigest, encodeDirectory, encodeNodeProperties, sha256, assertBunSupportsChunking, CHUNK_BYTES, SAFE_CHUNK_BYTES, MIN_BUN, COMPRESSOR, DIGEST_FUNCTION, OUTPUT_DIRECTORY_FORMAT or the wire and Merkle types.
vx-migrate: export only the four plugins
Section titled “vx-migrate: export only the four plugins”@vzn/vx-migrate no longer exports mapTurboWorkspace, mapNxWorkspace, nxExecCommand, parseNxGraph, readNxJsonFacts, TurboRemoteCache, NxRemoteCache, resolveTurboCacheConfig, resolveNxCacheConfig, turboRemoteAccess, artifactTag, VERCEL_API, MIN_SIGNATURE_KEY_LENGTH, migrateCmd, parseMigrateArgs or their types.
vx-lockfile: stop exporting the parser namespaces
Section titled “vx-lockfile: stop exporting the parser namespaces”@vzn/vx-lockfile no longer exports the pnpmLock, bunLock, npmLock and yarnLock namespaces.
vx-otel: stop exporting the OTLP builders
Section titled “vx-otel: stop exporting the OTLP builders”@vzn/vx-otel no longer exports buildLogsRequest, buildMetricsRequest, buildTraceRequest, resourceAttributes, runSpanAttributes, taskSpanAttributes, taskStatusCode, SEMCONV, VX_ATTR or the KeyValue, OtlpLogRecord and OtlpSpan types.
vx-github: stop exporting the Checks API helpers
Section titled “vx-github: stop exporting the Checks API helpers”@vzn/vx-github no longer exports buildCheckRunPayload, clampSummary, postCheckRun, resolveCheckRunEnv or the CheckRunEnv type.
plugins: refuse a plugin option value of the wrong kind
Section titled “plugins: refuse a plugin option value of the wrong kind”refuseUnknownOptions(factory, options, known) takes a PluginOptionKinds
drop native Windows code paths
Section titled “drop native Windows code paths”tasks no longer receive SYSTEMROOT, APPDATA and the other Windows essential env vars; native Windows is unsupported.
vx: type generated configs from the @vzn/vx/config entry
Section titled “vx: type generated configs from the @vzn/vx/config entry”vx init and vx-migrate now write import type { ProjectConfig } from '@vzn/vx/config', and @vzn/vx exports ./config.
vx-migrate: adopt Turbo and Nx only
Section titled “vx-migrate: adopt Turbo and Nx only”lage(), wireit(), workspaceScripts(), the lage-worker bin and vx-migrate —from lage|wireit|scripts are removed.
vx-migrate: drop moon support
Section titled “vx-migrate: drop moon support”moon(), mapMoonWorkspace and vx-migrate —from moon are removed.
cli: say in vx info when the sandbox runs untraced
Section titled “cli: say in vx info when the sandbox runs untraced”vx info’s JSON and vx mcp’s getWorkspaceInfo gain sandbox.untraced (string | null).
cli: map a workspace root’s repo-wide scripts in vx init
Section titled “cli: map a workspace root’s repo-wide scripts in vx init”No migration note.
cli: drop vx init’s readiness note where nothing waits
Section titled “cli: drop vx init’s readiness note where nothing waits”No migration note.
vx-migrate: cache an output no tracked top-level entry matches
Section titled “vx-migrate: cache an output no tracked top-level entry matches”No migration note.
vx: launch the npm binary from CommonJS, not ESM
Section titled “vx: launch the npm binary from CommonJS, not ESM”No migration note.
vx-migrate: cache an untracked /dist/ output
Section titled “vx-migrate: cache an untracked /dist/ output”No migration note.
config: take a bare —affected’s base from affectedBase
Section titled “config: take a bare —affected’s base from affectedBase”No migration note.
vx-migrate: map Turbo task tags to nothing
Section titled “vx-migrate: map Turbo task tags to nothing”the turbo-nx-support record moves turbo.json tasks.*.interruptible from not-supported to not-applicable.
vx-mcp: take a run id prefix in whyDidThisRerun
Section titled “vx-mcp: take a run id prefix in whyDidThisRerun”@vzn/vx packs src/orchestrator/run-id.ts in place of src/cli/run-id.ts, and vx-mcp’s whyDidThisRerun runId description now names a prefix.
vx-migrate: run Turbo root tasks with no root vx.config
Section titled “vx-migrate: run Turbo root tasks with no root vx.config”PLUGIN_HOOKS gains discover after config.
config: type-check unknown keys in defineWorkspace
Section titled “config: type-check unknown keys in defineWorkspace”defineWorkspace rejects keys the schema does not declare at type-check time. vx already refused them at load.
config: type-check unknown keys in defineProject
Section titled “config: type-check unknown keys in defineProject”defineProject rejects keys the schema does not declare at type-check time. vx already refused them when it loaded the config.
cli: remove the vx stats alias before 1.0
Section titled “cli: remove the vx stats alias before 1.0”vx stats is removed; run vx info, which prints the same report.
rename to @vzn/vx; drop run: { tasks } wrapper from config
Section titled “rename to @vzn/vx; drop run: { tasks } wrapper from config”No migration note.