The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 7, 2026 11:51pm UTC

No actionable comments were generated in the recent review. 🎉

sequenceDiagram
  participant CompileScript as compile.ts
  participant BundleFunction as bundle()
  participant BunCompiler as bun build --compile
  CompileScript->>BundleFunction: Bundle vlt and helper scripts
  BundleFunction-->>CompileScript: Return outdir and scripts
  CompileScript->>BunCompiler: Pass staged payload and forwarded arguments
  BunCompiler-->>CompileScript: Produce executable

Merge Risk: ⚪ Minimal · up to 3e203

The experimental executable is mergeable after normal checks; runtime behavior on cross-compiled targets remains untested.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

Bencher Report

🚨 1 Alert

sweet! thanks for the contribution @drawliin! we'll run some tests on our end, this is def exciting!

@lukekarrys mentioned and I believe it's a good idea, to potentially publish this first as a @vltpkg/bun-bin so that we could test it more (and have external folks trying it) ahead of adopting the single binary distribution, so bear with me but we may take a little more time before landing this one.

Thanks @ruyadorno !!

i have few ideas for further improvements: package this as @vltpkg/bun-bin, add smoke tests for the compiled CLI and background processes, verify it works on Linux/Windows, and explore platform detection and installation/fallback behavior under #1522

Let me know if you want me to tackle any of those while you’re testing internally.. i can split them into separate PRs

Perf review: Bun single-file executable vs the Node-driven JS bundle

A/B of this PR's bun build --compile artifact against the regular Node + JS bundle,
both built from 3e203cb (= v1.3.7 + this PR's 6 files), on one quiet box:
linux-x64, 4× Xeon @2.80 GHz, 15 GB RAM, kernel 6.12.107, Node 24.21.0, Bun 1.4.2,
hyperfine 1.19. Install numbers come from the vltpkg/benchmarks harness (0625fbf)
with BENCH_INCLUDE=vlt and VLT_REGISTRIES=npm=https://registry.npmjs.org/.

Four arms, so the runtime switch can be separated from the packaging switch:

Both Node arms get a warm NODE_COMPILE_CACHE outside the directory the harness wipes,
i.e. the Node side is measured at its best; Bun has no equivalent cache.

Verdict: the executable is functional on linux-x64 and faster than the Node bundle in
all 24 fixture × variation install cells (in both rounds) and in every start-up
measurement — but it loses badly on a cold page cache, and three Bun runtime behaviours
(one of them silent output truncation) need fixing before it could be the artifact users
get.

Start-up and small commands (warm, 40 runs each; median (mean ± σ) ms)

Cold module compile cache — a fresh CI container, or the first run after an upgrade.
Node's compile cache is wiped before every run; Bun has none to wipe, so it is unaffected:
node-pub 129.9 ms, node-min 122.1 ms, bun-sea 74.1 ms → −43.0 %.

Node version is not the story: node 24.21 99.9 ms, node 26.11 97.2 ms,
bun SEA 75.8 ms (still −22 % against the newer Node).

Where that start-up win actually comes from — an empty program on each runtime:

Subtracting the floor from vlt --version leaves 68 ms of CLI module init on Node and
70 ms on Bun. So for a trivial command the entire −27 % is the interpreter boot, not
faster CLI code; lazier module init is still the bigger lever and it would pay off on
both runtimes. Once there is real work to do the runtime does start to matter on its own
merits: subtracting the floor, query --view=json is 698 ms on Node vs 529 ms on Bun
(−24 % on the work itself), which is the same order as the install deltas below.

The detached helpers re-exec the whole 88.6 MB executable rather than running a 260 KB
script, and that is cheaper, not dearer: cache-unzip with nothing to do takes
56.8 ms under node vs 41.5 ms as a SEA re-exec (−27 %).

Installs — 96 cells, 4 fixtures × 6 variations × 2 rounds, 0 failures

Δ is the SEA against node-pub on pooled medians; ✓ marks the 22 of 24 cells where both
rounds moved the same way and |Δ| ≥ max(2 %, 2·SE). The two without a ✓ (cache+lockfile
on next and large) still favour the SEA in both rounds — they just carry single-run
registry/IO outliers large enough to widen the error bar.

Absolute medians for the two ends of that range:

The shape is informative: the gain is biggest where the install is dominated by our own
JS (no-op: lockfile parse, graph load, node_modules verification → −22…−26 %) and
smallest where it is dominated by syscalls and the network (cache+lockfile reify,
ci → −5…−10 %). Every fixture produced a byte-identical vlt-lock.json and the same
node_modules file count on both arms, and all 96 cells exited 0.

The one real regression: cold page cache

posix_fadvise(DONTNEED) on each arm's image before every run (verified: a full read of
the node binary goes 26 ms warm → 329 ms cold, the SEA 22 ms → 450 ms):

The SEA is ~2× slower on its first run after an install, a reboot, or in a container
whose layer cache has just been pulled. The mechanism is that it touches most of its image:
re-reading the binary straight after one --version run costs 192 ms versus 450 ms fully
cold, i.e. roughly 55–60 % of the 88.6 MB got paged in — whereas one node --version
leaves the 126 MB node binary essentially untouched (322 ms vs 329 ms cold).

Not much of that size is ours: an empty bun build --compile output is already
81.3 MB, so the Bun runtime is 92 % of the artifact and vlt's payload is the other
7.3 MB. Shrinking our bundle will not move this; it is a property of Bun SEAs.

So a user who already has Node downloads 2.9 MB today and would download 39 MB per
platform instead — and #1522's platform-specific packaging multiplies that across targets.

Memory

Peak RSS is consistently lower, which is the nicer half of the runtime swap:

Distribution claim checks out

With PATH=/nonexistent and a scrubbed environment the SEA still runs and completes a
cache+lockfile install of the large fixture (rc=0, 18 368 files) — no Node, no Bun, no
coreutils needed. One visible consequence: lifecycle scripts see
npm_config_user_agent=vlt/1.3.7 Bun/1.4.2 instead of vlt/1.3.7 Node.js/24
(@vltpkg/user-agent already handles this deliberately; flagging it only because any
package whose install script sniffs that string will now see Bun).

Three runtime-behaviour differences found while validating linux-x64

The PR notes Linux x64 "runtime testing remains", so I ran the functional pass first:
18/18 checks pass on linux-x64 for both arms — clean install, no-op, cache+lockfile,
query/ls in json/human/mermaid/svg/png (the resvg-wasm fix works), run/exec,
non-zero exit propagation, detached helpers. vlt-lock.json is byte-identical between
arms and node_modules has the same 18 368 files. So the executable is functional.

Three differences are worth fixing before this becomes a shipped artifact.

1. stdout is silently truncated at the pipe buffer (data loss, exit code 0).
cli-sdk/src/output.ts guards the drain on stream.writableLength:

export const flushStream = stream =>
  new Promise(res => {
    if (!stream.writableLength) return res()   // <- always true under Bun
    stream.write('', () => res())
  })

Under Bun process.stdout.writableLength is 0 even immediately after a 200 KB write,
so flushStream resolves at once and process.exit() discards everything still queued —
exactly the failure the comment above flushAndExit was written to prevent:

$ vlt query ':root > *' --view=json | wc -c
74887     # node-pub
65536     # bun-sea   <- cut at the 64 KiB pipe buffer, rc=0
$ vlt query ':root > *' --view=json > out.json   # redirect to a file: 74876, fine

Minimal repro — write 200 000 bytes to a pipe, then exit, and count what arrives
($ prog | wc -c):

                                      node      bun
  plain process.exit()               131072    131072   <- why flushStream exists
  writableLength-guarded flush       200000    131072   <- today's code
  unguarded stream.write('', cb)     200000    131072
  stream.end(cb)                     200000    200000
  process.exitCode = code            200000    200000   <- simplest fix

So flushAndExit wants to set process.exitCode and return (or stream.end(cb)),
rather than call process.exit() after a writableLength-guarded drain. vlt … | jq
and any CI job that captures output over 64 KiB loses the tail today.

2. ANSI escapes leak onto a non-TTY stderr. vlt writes stderr via console.error,
which Bun colours unconditionally; Node defers to supports-color:

$ vlt not-a-command 2> err.txt ; wc -c err.txt
448 err.txt   # node-pub, 0 escape sequences
487 err.txt   # bun-sea, 4 lines wrapped in ESC[0m ESC[31m … ESC[0m

3. process.title is a no-op in Bun, so the background helpers lose their names.
The four code-split helpers set process.title = 'vlt-cache-unzip' etc. Under the SEA
the child shows up as the executable:

node-pub:  3626563 vlt-cache-unzip  vlt-cache-unzip
bun-sea:   3626034 vlt-bun          …/raw/vlt-bun /$bunfs/root/payload/cache-unzip-src-unzip.js …

Anything that keys on the title breaks — including vltpkg/benchmarks'
wait_vlt_children, which greps ^vlt-(cache|security)-. Benchmarking the SEA with the
stock helper leaks a detached unzip child into the next timed run and into
clean_vlt_cache's cache removal. I had to widen the pattern to match the helper
script path instead to get trustworthy install numbers:

-  while pgrep -u "$(id -u)" -f '^vlt-(cache|security)-|^[^ ]*node [^ ]*/(cache-unzip-src-unzip|registry-client-src-revalidate)\.js( |$)'
+  while pgrep -u "$(id -u)" -f '^vlt-(cache|security)-|/(cache-unzip-src-unzip|registry-client-src-revalidate|rollback-remove-src-remove|security-archive-src-update-expired)\.js( |$)'

Where the win comes from, and what the build leaves on the table

bun-js ≈ bun-sea on every command (within 3 %), and node-pub ≈ node-min.
So the gain is the Bun runtime, not the single-file packaging, and not minification.
Packaging it as one executable is a distribution win (no Node needed — confirmed above),
and once the image is in the page cache it costs nothing measurable at runtime. That is a
good result for the PR; the cold-page-cache penalty above is the price of the packaging,
not of the runtime.

It does, however, leave the one big Bun startup lever unused. compile.ts embeds the
bundle as an --asset directory and reaches it with a runtime import() of a
/$bunfs/… file URL, so the CLI's 4.75 MB of JS (98 chunks) is outside the compiled
module graph:
Bun re-parses it from source on every run, with no bytecode and no compile cache (Node at
least has module.enableCompileCache()). Passing --bytecode to try to fix that fails
outright today, because the generated launcher is ESM with top-level await:

$ node src/compile.ts out --bytecode
error: "await" can only be used inside an "async" function
   at /tmp/vlt-compile-…/launcher.js:8:9     (and :10:9)

A CJS launcher would compile, but would not help on its own: bytecode only covers the
entry graph, and the payload is an asset. Getting it would mean making payload/vlt.js
the compile entry (and giving the helper dispatch another way to resolve
import.meta.dirname). Worth filing against #1522 rather than blocking here.

Two smaller build notes:

• compile.ts hard-codes minify: true, but minification is worth ~0 at runtime on both
  runtimes (node-pub vs node-min, and bun-js runs the minified bundle). It only
  costs you readable stack traces in the one artifact users cannot easily re-run under a
  debugger. Consider dropping it, or pairing it with sourcemap.
• Everything here is the native linux-x64 build (node src/compile.ts out, no
  --target), so the PR's open "Linux x64 … runtime testing remains" item is covered for
  that case. Windows and the cross-compiled targets are still untested.