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

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.