Skip to content

bun-first

Bun-First — Bun Is the Default Runtime for Studio Tooling

Section titled “Bun-First — Bun Is the Default Runtime for Studio Tooling”

Studio decision 2026-11-04: Bun for the whole ecosystem. When you author or edit a workflow, package.json, Dockerfile or script, Bun is the default package manager, script runner and test runner.

  • CI: oven-sh/setup-bun@v2, bun install --frozen-lockfile, bun run <script>, bun test, bunx <pkg>@<pin>. Not actions/setup-node plus an npm, pnpm or yarn install. In a job with no setup-node, run bunx --bun: bare bunx runs the node shebang (docs/ci-cd-trigger-design.md Rule 17).
  • package.json: commit bun.lock; scripts call bun, not node / npx; no tsx / ts-node / nodemon.
  • Dockerfile: a new tooling image starts from oven/bun.
  • No churn: apply it when you write a file or are already editing it; never rewrite a working workflow only to switch runtime.

State which one in a comment beside the Node usage.

  1. Host-bundled Node — Cocos Creator extensions, Electron, React Native Metro: the host picks the runtime.
  2. Consumer-machine scripts — kit hooks and scripts stay portable .cjs that run under Node and Bun, Windows included; never assume Bun exists.
  3. Production service runtime — a per-app decision, proven with a canary; the tooling around it stays Bun.
  4. Package-pinned tooling — a tool whose docs require Node (mermaid-cli’s mmdc; V8 coverage, which Bun ignores).

Cloudflare docs (verified 2026-11-04): cf needs Node 22.18+, Bun is not supported, and on Bun the commands that load cloudflare.config.ts fail. Bun may INSTALL cf (bun add -g cf). Measured on Bun 1.4.3: bunx cf@<pin> keeps the #!/usr/bin/env node shebang on Node while a node is on PATH, and silently runs cf ON Bun through a built-in shim when none is. Default: a job or container that runs cf sets up Node 26 (studio policy, 2026-11-04; satisfies Cloudflare’s 22.18+ floor) next to Bun. The failing set is narrow: only commands that load cloudflare.config.ts break on Bun. A no-config command ran fine under bun --bun x --no-install cf (deploy --prebuilt, theonekit-docs run 41775085033, 2026-11-04), so where the runner’s Node is too old and setup-node is unavailable (kits), that form is acceptable; never run a config-loading command on Bun. Workers run on workerd, never Bun or Node.

Advisory by design for studio app repos: no hook or CI check enforces this default yet. Kit repos are already covered by the bun-only CI guard (theonekit-release-action check-bun-only.mjs), which fails a live file that invokes node/npm/npx/pnpm/yarn; its local-exempt list is where an exception above is recorded.