Bun Runtime

1---2name: bun-runtime3description: Bun as runtime, package manager, bundler, and test runner. When to choose Bun vs Node, migration notes, and Vercel support.4origin: ECC5---6 7# Bun Runtime8 9Bun is a fast all-in-one JavaScript runtime and toolkit: runtime, package manager, bundler, and test runner.10 11## When to Use12 13- **Prefer Bun** for: new JS/TS projects, scripts where install/run speed matters, Vercel deployments with Bun runtime, and when you want a single toolchain (run + install + test + build).14- **Prefer Node** for: maximum ecosystem compatibility, legacy tooling that assumes Node, or when a dependency has known Bun issues.15 16Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/tests, or configuring Bun on Vercel or other platforms.17 18## How It Works19 20- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).21- **Package manager**: `bun install` is significantly faster than npm/yarn. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary).22- **Bundler**: Built-in bundler and transpiler for apps and libraries.23- **Test runner**: Built-in `bun test` with Jest-like API.24 25**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.26 27**Vercel**: Set runtime to Bun in project settings. Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.28 29## Examples30 31### Run and install32 33```bash34# Install dependencies (creates/updates bun.lock or bun.lockb)35bun install36 37# Run a script or file38bun run dev39bun run src/index.ts40bun src/index.ts41```42 43### Scripts and env44 45```bash46bun run --env-file=.env dev47FOO=bar bun run script.ts48```49 50### Testing51 52```bash53bun test54bun test --watch55```56 57```typescript58// test/example.test.ts59import { expect, test } from "bun:test";60 61test("add", () => {62  expect(1 + 2).toBe(3);63});64```65 66### Runtime API67 68```typescript69const file = Bun.file("package.json");70const json = await file.json();71 72Bun.serve({73  port: 3000,74  fetch(req) {75    return new Response("Hello");76  },77});78```79 80## Best Practices81 82- Commit the lockfile (`bun.lock` or `bun.lockb`) for reproducible installs.83- Prefer `bun run` for scripts. For TypeScript, Bun runs `.ts` natively.84- Keep dependencies up to date; Bun and the ecosystem evolve quickly.