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>. Notactions/setup-nodeplus an npm, pnpm or yarn install. In a job with nosetup-node, runbunx --bun: barebunxruns the node shebang (docs/ci-cd-trigger-design.mdRule 17). - package.json: commit
bun.lock; scripts callbun, notnode/npx; notsx/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.
Exceptions that may stay on Node
Section titled “Exceptions that may stay on Node”State which one in a comment beside the Node usage.
- Host-bundled Node — Cocos Creator extensions, Electron, React Native Metro: the host picks the runtime.
- Consumer-machine scripts — kit hooks and scripts stay portable
.cjsthat run under Node and Bun, Windows included; never assumeBunexists. - Production service runtime — a per-app decision, proven with a canary; the tooling around it stays Bun.
- Package-pinned tooling — a tool whose docs require Node (mermaid-cli’s
mmdc; V8 coverage, which Bun ignores).
cf is the named exception
Section titled “cf is the named exception”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.
Enforcement
Section titled “Enforcement”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.