Bun Runtime

Bun is a fast all-in-one JavaScript runtime and toolkit: runtime, package manager, bundler, and test runner.

When to Use

• 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).
• Prefer Node for: maximum ecosystem compatibility, legacy tooling that assumes Node, or when a dependency has known Bun issues.

Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/tests, or configuring Bun on Vercel or other platforms.

How It Works

• Runtime: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).
• 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).
• Bundler: Built-in bundler and transpiler for apps and libraries.
• Test runner: Built-in bun test with Jest-like API.

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.

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.

Examples

Run and install

bash
1# Install dependencies (creates/updates bun.lock or bun.lockb)
2bun install
3
4# Run a script or file
5bun run dev
6bun run src/index.ts
7bun src/index.ts

Scripts and env

bash
1bun run --env-file=.env dev
2FOO=bar bun run script.ts

Testing

bash
1bun test
2bun test --watch

typescript
1// test/example.test.ts
2import { expect, test } from "bun:test";
3
4test("add", () => {
5  expect(1 + 2).toBe(3);
6});

Runtime API

typescript
1const file = Bun.file("package.json");
2const json = await file.json();
3
4Bun.serve({
5  port: 3000,
6  fetch(req) {
7    return new Response("Hello");
8  },
9});

Best Practices

• Commit the lockfile (bun.lock or bun.lockb) for reproducible installs.
• Prefer bun run for scripts. For TypeScript, Bun runs .ts natively.
• Keep dependencies up to date; Bun and the ecosystem evolve quickly.