build: bun-standalone — reduced-footprint --compile runtime

.buildkite/ci.mjs

@@ -525,13 +525,15 @@ function getTestAgent(platform, options) {
  * @param {Target} target
  * @param {PipelineOptions} options
  * @param {"cpp-only" | "rust-only" | "link-only"} mode
+ * @param {{standalone?: boolean}} [extra]
  * @returns {string}
  */
-function getBuildArgs(target, options, mode) {
+function getBuildArgs(target, options, mode, extra = {}) {
   const { os, arch, abi, baseline, profile, crossCompile } = target;
   const { canary } = options;
 
   const args = [`--profile=ci-${mode}`];
+  if (extra.standalone) args.push("--standalone=on");
 
   // rust-only cross-compiles (linux host → linux/freebsd targets); os/arch/abi
   // must all be explicit — host detection (detectLinuxAbi checks
@@ -570,9 +572,10 @@ function getBuildArgs(target, options, mode) {
  * @param {Target} target
  * @param {PipelineOptions} options
  * @param {"cpp-only" | "rust-only" | "link-only"} mode
+ * @param {{standalone?: boolean}} [extra]
  * @returns {string}
  */
-function getBuildCommand(target, options, mode) {
+function getBuildCommand(target, options, mode, extra) {
   // Windows code signing is handled by a dedicated 'windows-sign' step after
   // all Windows builds complete — see getWindowsSignStep(). smctl is x64-only,
   // so signing on the build agent wouldn't work for ARM64 anyway.
@@ -582,7 +585,7 @@ function getBuildCommand(target, options, mode) {
   // is wrong. PATH on the agent has node via bootstrap.sh.
   // --experimental-strip-types for Node 24's .ts support (unflagged in
   // 25+; drop once CI bumps past the ABI-141 blocker).
-  return `node --experimental-strip-types scripts/build.ts ${getBuildArgs(target, options, mode)}`;
+  return `node --experimental-strip-types scripts/build.ts ${getBuildArgs(target, options, mode, extra)}`;
 }
 
 /**
@@ -659,6 +662,63 @@ function getLinkBunStep(platform, options) {
   };
 }
 
+/**
+ * Second cargo build for the reduced-footprint `bun-standalone` runtime
+ * (`--features standalone`). Same agent fan-out as build-rust.
+ *
+ * @param {Platform} platform
+ * @param {PipelineOptions} options
+ * @returns {Step}
+ */
+function getBuildRustStandaloneStep(platform, options) {
+  return {
+    key: `${getTargetKey(platform)}-build-rust-standalone`,
+    retry: getRetry(),
+    label: `${getTargetLabel(platform)} - build-rust-standalone`,
+    agents: getRustAgent(platform, options),
+    cancel_on_build_failing: isMergeQueue(),
+    command: getBuildCommand(platform, options, "rust-only", { standalone: true }),
+    timeout_in_minutes: 35,
+  };
+}
+
+/**
+ * Second link for `bun-standalone`. Reuses the same `build-cpp` archive
+ * (the C++ side is identical); only the Rust staticlib differs.
+ *
+ * @param {Platform} platform
+ * @param {PipelineOptions} options
+ * @returns {Step}
+ */
+function getLinkBunStandaloneStep(platform, options) {
+  return {
+    key: `${getTargetKey(platform)}-build-bun-standalone`,
+    label: `${getTargetLabel(platform)} - build-bun-standalone`,
+    depends_on: [`${getTargetKey(platform)}-build-cpp`, `${getTargetKey(platform)}-build-rust-standalone`],
+    agents: getLinkBunAgent(platform, options),
+    retry: getRetry(),
+    cancel_on_build_failing: isMergeQueue(),
+    env: {
+      ASAN_OPTIONS: "allow_user_segv_handler=1:disable_coredump=0:detect_leaks=0",
+    },
+    command: getBuildCommand(platform, options, "link-only", { standalone: true }),
+  };
+}
+
+/**
+ * Whether to build `bun-standalone` for this platform. Only the plain
+ * release lanes that ship to users for `bun build --compile` — not asan,
+ * and not Android/FreeBSD until --compile supports those targets.
+ *
+ * @param {Platform} platform
+ */
+function shouldBuildStandalone(platform) {
+  if ((platform.profile ?? "release") !== "release") return false;
+  if (platform.abi === "android") return false;
+  if (platform.os === "freebsd") return false;
+  return true;
+}
+
 /**
  * Returns the artifact triplet for a platform, e.g. "bun-linux-aarch64" or "bun-linux-x64-musl-baseline".
  * Matches the naming convention in cmake/targets/BuildBun.cmake.
@@ -803,6 +863,11 @@ function getTestBunStep(platform, options, testOptions = {}) {
   const { buildId, testFiles } = testOptions;
 
   const args = [`--step=${getTargetKey(platform)}-build-bun`];
+  // bun-standalone is built by a sibling step; runner.node.mjs downloads it
+  // best-effort and exports BUN_STANDALONE_EXE for test/cli/standalone-binary.test.ts.
+  if (shouldBuildStandalone(platform)) {
+    args.push(`--standalone-step=${getTargetKey(platform)}-build-bun-standalone`);
+  }
   if (buildId) {
     args.push(`--build-id=${buildId}`);
   }
@@ -817,6 +882,11 @@ function getTestBunStep(platform, options, testOptions = {}) {
   const depends = [];
   if (!buildId) {
     depends.push(`${getTargetKey(platform)}-build-bun`);
+    if (shouldBuildStandalone(platform)) {
+      // Soft dependency: wait for the standalone build so the artifact exists,
+      // but don't block tests if that step failed.
+      depends.push({ step: `${getTargetKey(platform)}-build-bun-standalone`, allow_failure: true });
+    }
   }
 
   return {
@@ -904,6 +974,12 @@ function getWindowsSignStep(windowsPlatforms, options) {
     const stepKey = `${getTargetKey(platform)}-build-bun`;
     artifacts.push(`${triplet}-profile.zip`, `${triplet}.zip`);
     buildSteps.push(stepKey, stepKey);
+    if (shouldBuildStandalone(platform)) {
+      const standaloneTriplet = triplet.replace(/^bun-/, "bun-standalone-");
+      const standaloneStepKey = `${getTargetKey(platform)}-build-bun-standalone`;
+      artifacts.push(`${standaloneTriplet}-profile.zip`, `${standaloneTriplet}.zip`);
+      buildSteps.push(standaloneStepKey, standaloneStepKey);
+    }
   }
 
   // Signing runs on a real Windows x64 machine (smctl; doesn't work on
@@ -912,7 +988,10 @@ function getWindowsSignStep(windowsPlatforms, options) {
   return {
     key: "windows-sign",
     label: `${getBuildkiteEmoji("windows")} sign`,
-    depends_on: windowsPlatforms.map(p => `${getTargetKey(p)}-build-bun`),
+    depends_on: windowsPlatforms.flatMap(p => [
+      `${getTargetKey(p)}-build-bun`,
+      ...(shouldBuildStandalone(p) ? [`${getTargetKey(p)}-build-bun-standalone`] : []),
+    ]),
     agents: getEc2Agent({ os: "windows", arch: "x64", release: "2019" }, options, {
       instanceType: getAzureVmSize("windows", "x64", "test"),
     }),
@@ -938,7 +1017,14 @@ function getWindowsSignStep(windowsPlatforms, options) {
  * @returns {Step}
  */
 function getBinarySizeStep(releasePlatforms, options, { recordOnly = false } = {}) {
-  const targets = releasePlatforms.map(p => ({ triplet: getTargetTriplet(p) }));
+  const standalone = releasePlatforms.filter(shouldBuildStandalone);
+  const targets = [
+    ...releasePlatforms.map(p => ({ triplet: getTargetTriplet(p) })),
+    // packageAndUpload sets `binary-size:bun-standalone-<triplet>` from the
+    // standalone link step; track those alongside the full binary so size
+    // regressions in either variant trip the threshold.
+    ...standalone.map(p => ({ triplet: getTargetTriplet(p).replace(/^bun-/, "bun-standalone-") })),
+  ];
   const args = [`--targets '${JSON.stringify(targets)}'`, `--threshold-mb ${BINARY_SIZE_THRESHOLD_MB}`];
   if (recordOnly) args.push("--no-fail");
   if (!options.canary) args.push("--release");
@@ -951,7 +1037,10 @@ function getBinarySizeStep(releasePlatforms, options, { recordOnly = false } = {
       options,
       { instanceType: "c8g.large" },
     ),
-    depends_on: releasePlatforms.map(p => `${getTargetKey(p)}-build-bun`),
+    depends_on: [
+      ...releasePlatforms.map(p => `${getTargetKey(p)}-build-bun`),
+      ...standalone.map(p => `${getTargetKey(p)}-build-bun-standalone`),
+    ],
     allow_dependency_failure: true,
     soft_fail: !!options.skipSizeCheck,
     retry: {
@@ -977,9 +1066,13 @@ function getReleaseStep(buildPlatforms, options, { signed = false } = {}) {
 
   // When signing ran, depend on windows-sign instead of the raw Windows builds
   // so we wait for signed artifacts before releasing.
+  const buildKeys = p => [
+    `${getTargetKey(p)}-build-bun`,
+    ...(shouldBuildStandalone(p) ? [`${getTargetKey(p)}-build-bun-standalone`] : []),
+  ];
   const depends_on = signed
-    ? [...buildPlatforms.filter(p => p.os !== "windows").map(p => `${getTargetKey(p)}-build-bun`), "windows-sign"]
-    : buildPlatforms.map(platform => `${getTargetKey(platform)}-build-bun`);
+    ? [...buildPlatforms.filter(p => p.os !== "windows").flatMap(buildKeys), "windows-sign"]
+    : buildPlatforms.flatMap(buildKeys);
 
   return {
     key: "release",
@@ -1468,6 +1561,10 @@ async function getPipeline(options = {}) {
         steps.push(getBuildCppStep(target, options));
         steps.push(getBuildRustStep(target, options));
         steps.push(getLinkBunStep(target, options));
+        if (shouldBuildStandalone(target)) {
+          steps.push(getBuildRustStandaloneStep(target, options));
+          steps.push(getLinkBunStandaloneStep(target, options));
+        }
 
         if (needsBaselineVerification(target)) {
           steps.push(getVerifyBaselineStep(target, options));

.buildkite/scripts/upload-release.sh

@@ -125,7 +125,7 @@ function download_buildkite_artifact() {
   # (build-bun unsigned, windows-sign signed). Pin to the sign step to
   # guarantee we get the signed one.
   local step_args=()
-  if [[ -n "$WINDOWS_ARTIFACT_STEP" && "$name" == bun-windows-* ]]; then
+  if [[ -n "$WINDOWS_ARTIFACT_STEP" && ( "$name" == bun-windows-* || "$name" == bun-standalone-windows-* ) ]]; then
     step_args=(--step "$WINDOWS_ARTIFACT_STEP")
   fi
   run_command buildkite-agent artifact download "$name" "$dir" "${step_args[@]}"
@@ -238,6 +238,36 @@ function create_release() {
     bun-windows-aarch64-profile.zip
   )
 
+  # Reduced-footprint --compile runtime. Same triplets minus android/freebsd
+  # (see shouldBuildStandalone in .buildkite/ci.mjs). buildkite-agent artifact
+  # download without --step searches the whole build, so these are picked up
+  # from the *-build-bun-standalone steps.
+  local standalone_artifacts=(
+    bun-standalone-darwin-aarch64.zip
+    bun-standalone-darwin-aarch64-profile.zip
+    bun-standalone-darwin-x64.zip
+    bun-standalone-darwin-x64-profile.zip
+    bun-standalone-linux-aarch64.zip
+    bun-standalone-linux-aarch64-profile.zip
+    bun-standalone-linux-x64.zip
+    bun-standalone-linux-x64-profile.zip
+    bun-standalone-linux-x64-baseline.zip
+    bun-standalone-linux-x64-baseline-profile.zip
+    bun-standalone-linux-aarch64-musl.zip
+    bun-standalone-linux-aarch64-musl-profile.zip
+    bun-standalone-linux-x64-musl.zip
+    bun-standalone-linux-x64-musl-profile.zip
+    bun-standalone-linux-x64-musl-baseline.zip
+    bun-standalone-linux-x64-musl-baseline-profile.zip
+    bun-standalone-windows-x64.zip
+    bun-standalone-windows-x64-profile.zip
+    bun-standalone-windows-x64-baseline.zip
+    bun-standalone-windows-x64-baseline-profile.zip
+    bun-standalone-windows-aarch64.zip
+    bun-standalone-windows-aarch64-profile.zip
+  )
+  artifacts+=("${standalone_artifacts[@]}")
+
   function upload_artifact() {
     local artifact="$1"
     download_buildkite_artifact "$artifact"
@@ -255,6 +285,15 @@ function create_release() {
     upload_artifact "$artifact"
   done
 
+  # bun-standalone-* zips ship alongside the regular zips. Derived from the
+  # main artifact list so a new platform can't be forgotten here. Best-effort:
+  # a missing standalone artifact warns but doesn't abort the release
+  # (download_buildkite_artifact's `exit 1` only kills the subshell).
+  for artifact in "${artifacts[@]}"; do
+    local standalone="${artifact/bun-/bun-standalone-}"
+    ( upload_artifact "$standalone" ) || echo "warn: skipping missing standalone artifact: $standalone"
+  done
+
   update_github_release "$tag"
   create_sentry_release "$tag"
   send_discord_announcement "$tag"

Cargo.toml

@@ -188,7 +188,7 @@ warnings = { level = "deny", priority = -1 }
 # `bun_asan` is set via RUSTFLAGS (`--cfg=bun_asan` + `--check-cfg=cfg(bun_asan)`)
 # by scripts/build/rust.ts for asan builds; register it here so a plain
 # `cargo build` / `cargo check` (without those flags) doesn't warn.
-unexpected_cfgs = { level = "warn", check-cfg = ['cfg(bun_asan)'] }
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(bun_asan)', 'cfg(bun_standalone)'] }
 # link.exe unconditionally prints "Creating library X.dll.lib and object
 # X.dll.exp" to stdout when linking each proc-macro DLL on Windows hosts;
 # there is no linker flag to suppress it. The lint already exempts itself

docs/standalone-binary.md

@@ -0,0 +1,101 @@
+# `bun-standalone` — the `--compile` runtime binary
+
+`bun-standalone` is a second build of the `bun` executable with the toolkit
+subcommands compiled out. It exists so that `bun build --compile` can produce
+smaller single-file executables: the embedded runtime only needs to _run_
+JavaScript, not bundle it, install packages, or run a test suite.
+
+The binary name is `bun-standalone` (`bun-standalone.exe` on Windows). Debug
+and instrumented variants follow the same suffix scheme as the full binary
+(`bun-standalone-debug`, `bun-standalone-asan`, …).
+
+## What's removed
+
+The CLI dispatch for every subcommand other than the run path is replaced
+with an error message pointing at the full Bun install:
+
+- `bun build`
+- `bun test`
+- `bun install` / `add` / `remove` / `update` / `link` / `unlink` / `pm` /
+  `outdated` / `publish` / `audit` / `why` / `info` / `patch`
+- `bun init` / `create` / `x` / `upgrade`
+
+`bun <file>`, `bun run`, `bun --eval/--print`, `bun exec`, `bun repl`, and
+the `node`-shim entry remain.
+
+The dispatch sever is the load-bearing change: with the per-tag `exec_*`
+bodies gone, `--gc-sections` (driven by `.llvm_addrsig`, which both rustc and
+clang emit) drops the now-unreferenced `bundle_v2` / `PackageManager` /
+`TestCommand` machinery from the final image. The C++ object set is unchanged
+— `build-cpp` produces one archive that both `bun` and `bun-standalone` link
+against.
+
+## How it's built
+
+`cfg.standalone` (a boolean on the build `Config`) drives three things:
+
+- `cargo build -p bun_bin --features standalone` with
+  `RUSTFLAGS="… --cfg=bun_standalone"` into a separate `--target-dir`
+  (`rust-target-standalone/`), so the full and standalone staticlibs can
+  coexist in one build directory.
+- the linked executable is named `bun-standalone[-profile]` and the
+  stripped output `bun-standalone`.
+- `bun_core::build_options::STANDALONE_BUILD` is `true`.
+
+Gating in Rust is on `cfg(bun_standalone)` (the global RUSTFLAG), not
+`cfg(feature = "standalone")`, so any crate can branch on it without
+threading a cargo feature through the workspace graph. The cargo feature on
+`bun_bin` → `bun_runtime` exists so `cargo check -p bun_bin --features
+standalone` is a valid invocation.
+
+Locally:
+
+```sh
+bun run build:standalone           # release → build/release-standalone/bun-standalone
+bun run build:standalone:debug     # debug   → build/debug-standalone/bun-standalone-debug
+```
+
+In CI, each release platform gets two extra steps that reuse the existing
+`build-cpp` artifact:
+
+```
+<target>-build-cpp               (shared)
+<target>-build-rust              ────────► <target>-build-bun
+<target>-build-rust-standalone   ────────► <target>-build-bun-standalone
+```
+
+`scripts/build/ci.ts::downloadArtifacts` derives the rust sibling from the
+step-key suffix; the cpp sibling is always `<target>-build-cpp`. Packaged
+artifacts are `bun-standalone-<os>-<arch>[-musl][-baseline].zip`.
+
+## Size
+
+Linux-x64 release, non-LTO, measured on this branch:
+
+|                           |          bytes |        MB |
+| ------------------------- | -------------: | --------: |
+| stripped `bun`            |     70,389,048 |     67.13 |
+| stripped `bun-standalone` |     62,392,896 |     59.50 |
+| **delta**                 | **−7,996,152** | **−7.63** |
+
+`bloaty` section diff: `.text` −6.80 MB, `.rodata` −849 KB.
+
+Per-crate VM size from `bloaty -d compileunits` (full → standalone):
+
+| crate             | full MB | standalone MB |     Δ |
+| ----------------- | ------: | ------------: | ----: |
+| `bun_runtime`     |    6.45 |          4.75 | −1.70 |
+| `bun_install`     |    2.03 |          0.03 | −2.00 |
+| `bun_css`         |    1.77 |             0 | −1.77 |
+| `bun_bundler`     |    1.61 |          0.44 | −1.17 |
+| `bun_css_jsc`     |    0.10 |             0 | −0.10 |
+| `bun_install_jsc` |    0.05 |             0 | −0.05 |
+
+The remaining `bun_bundler` 0.44 MB is the `Transpiler` half (single-file
+TS→JS, options/defines/cache, `analyze_transpiled_module`) which is
+structurally embedded in `VirtualMachine` and required by the module loader.
+
+The < 35 MB target additionally requires shipping a reduced ICU data file
+(small-icu ≈ 5 MB instead of 24 MB) — a WebKit-prebuilt change. The hard
+floor with full ICU is JSC 22.9 MB + ICU 23.7 MB + bindings/crypto/codecs
+≈ 57 MB.

package.json

@@ -50,6 +50,8 @@
     "build:asan": "bun scripts/build.ts --profile=release-asan --build-dir=build/release-asan",
     "build:logs": "bun scripts/build.ts --profile=release --logs=on --build-dir=build/release-logs",
     "build:smol": "bun scripts/build.ts --profile=release --build-type=MinSizeRel --build-dir=build/release-smol",
+    "build:standalone": "bun scripts/build.ts --profile=release --standalone=on --build-dir=build/release-standalone",
+    "build:standalone:debug": "bun scripts/build.ts --profile=debug --standalone=on --build-dir=build/debug-standalone",
     "build:local": "bun scripts/build.ts --profile=debug-local --build-dir=build/debug-local",
     "build:release:local": "bun scripts/build.ts --profile=release-local --build-dir=build/release-local",
     "run:linux": "docker run --rm  -v \"$PWD:/root/bun/\" -w /root/bun ghcr.io/oven-sh/bun-development-docker-image",