Bun Runtime

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.

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.

node script.js

bun run script.js

bun script.js

bun install

npm install

bun run

bun x

bun run build

bun build ./src/index.ts --outdir=dist

bun install --frozen-lockfile

Examples

Run and install

# Install dependencies (creates/updates bun.lock or bun.lockb)
bun install

# Run a script or file
bun run dev
bun run src/index.ts
bun src/index.ts

Scripts and env

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

Testing

bun test
bun test --watch

// test/example.test.ts
import { expect, test } from "bun:test";

test("add", () => {
  expect(1 + 2).toBe(3);
});

Runtime API

const file = Bun.file("package.json");
const json = await file.json();

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello");
  },
});

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.