bun-expertise

When to use this

• A repo has bun.lock, a bunfig.toml, or a package.json with "engines": { "bun": ... }.
• Writing a script, test, dev-server, or build step and deciding which Bun primitive to reach for.
• Considering a Node/npm tool (tsx, ts-node, vitest, dotenv, nodemon) and unsure whether Bun already covers it.

Documentation

Targets Bun 1.2+ (text bun.lock, Bun.serve routes, bun:sqlite). Node-compat coverage and newer APIs shift between minors — check the live docs. Canonical entry points:

• Docs root: https://bun.com/docs
• llms.txt index (all pages): https://bun.com/docs/llms.txt
• Runtime: https://bun.com/docs/runtime
• Package manager: https://bun.com/docs/pm/cli/install
• Test runner: https://bun.com/docs/test
• Bundler: https://bun.com/docs/bundler
• Node compatibility status: https://bun.com/docs/runtime/nodejs-compat

WebFetch the Node-compat page when unsure whether a node:* API works yet — it's an ongoing effort, not complete.

Mental model

The concepts that decide when to reach for a Bun primitive:

• One binary, several tools. Bun is a single executable bundling a runtime, package manager, bundler, test runner, and shell. In a Bun project, default to the Bun primitive over the Node-ecosystem equivalent (table below) — it's already there, faster, and needs no extra dependency.
• TS/JSX run directly, but aren't type-checked. Bun transpiles .ts/.tsx on the fly and honours tsconfig.json for paths/JSX/target — no tsx/ts-node/transpile step. It does not type-check at runtime; still run tsc --noEmit in CI. See [[typescript-strict-expertise]].
• Web-standard APIs first. Bun implements fetch, Request/Response, URL, WebSocket, ReadableStream natively. Server and HTTP code built on these stays portable; Bun.*/bun:* APIs do not (see Portability).
• Node compatibility is good but partial. process, fs, path, http, crypto, Buffer, and most node:* work. Reach for Node APIs when the Bun equivalent doesn't exist or the code must also run on Node.
• Bun-specific APIs are a portability tradeoff. Bun.serve, Bun.file, bun:sqlite, $ are faster and ergonomic but lock code to Bun. Use them freely in scripts/tests; keep published library and cross-runtime code standards-based.

In a Bun project, default to the Bun primitive rather than the Node ecosystem equivalent:

Need	Don't reach for	Use
Run TypeScript	tsx, ts-node, node --loader	bun run script.ts (runs TS directly)
Install deps	npm install, pnpm install	bun install (uses bun.lock)
Run a package binary	npx	bunx (or bun x)
Test runner	vitest, jest	bun test
Watch/restart	nodemon, node --watch	bun --watch / bun --hot
Bundle	esbuild, webpack	bun build
Read env files	dotenv	Bun reads .env automatically
HTTP server	express, fastify for trivial cases	Bun.serve({ ... })
Read/write files	fs.promises.readFile/writeFile	Bun.file(path) / Bun.write(path, data)
Spawn processes	child_process.spawn	Bun.spawn([...]) / $\...`` shell
Embedded SQL	better-sqlite3	import { Database } from "bun:sqlite"
Hash a password	bcrypt	Bun.password.hash/verify

Core idioms

Running scripts

bun run scripts/validate.ts        # runs TS directly, no transpile step
bun script.ts                      # short form
bun --watch run server.ts          # restart on file change
bun --hot run server.ts            # hot-reload without dropping state

package.json scripts run under Bun when invoked with bun run <name>. bun <name> also works if it doesn't collide with a built-in command.

Package management

bun install                        # install from package.json + bun.lock
bun add zod                        # add a dependency
bun add -d @types/bun              # dev dependency
bun add -g <tool>                  # global
bun update                         # update within ranges
bun outdated                       # show what's behind

• The lockfile is bun.lock (text, since Bun 1.2; older repos may have binary bun.lockb).
• Workspaces: declare "workspaces": ["packages/*"] in the root package.json; bun install links them.
• bunx <pkg> runs a package binary without installing it (like npx).

bun test

import { test, expect, describe, mock, beforeEach } from "bun:test";

describe("foo", () => {
  test("works", () => {
    expect(1 + 1).toBe(2);
  });
});

• Import from "bun:test", not "vitest". Jest-compatible expect matchers.
• Discovery: *.test.ts, *.spec.ts, *.test.tsx, etc.
• Run with bun test. Filter by name with bun test -t "pattern", or pass a path. Watch with --watch, coverage with --coverage.
• Mocks: mock(fn) is the vi.fn() equivalent; mock.module("./x", () => ({...})) stubs a module. Lifecycle hooks beforeEach/afterAll come from "bun:test" too.

Files

const text = await Bun.file("config.json").text();
const json = await Bun.file("config.json").json();
const buf = await Bun.file("blob.bin").arrayBuffer();

await Bun.write("out.txt", "hello");
await Bun.write("out.json", JSON.stringify({ foo: 1 }));
await Bun.write("copy.bin", Bun.file("in.bin")); // streamed copy

Bun.file() is lazy — it doesn't touch disk until you read it. Check existence with await Bun.file(path).exists().

HTTP server

Bun.serve({
  port: 3000,
  routes: {
    "/": new Response("hi"),
    "/users/:id": (req) => Response.json({ id: req.params.id }),
  },
  fetch(req) {
    return new Response("not found", { status: 404 });
  },
});

• Standard Request/Response/URL — no framework needed for simple servers. routes (Bun 1.2+) gives path-param routing; fetch is the fallback.
• WebSockets: pass a websocket handler and call server.upgrade(req) inside fetch.
• Hot reload during dev with bun --hot run server.ts.

Shell

import { $ } from "bun";
const branch = (await $`git rev-parse --abbrev-ref HEAD`.text()).trim();
await $`mkdir -p dist && cp ${file} dist/`; // interpolation auto-escapes

$ runs a cross-platform shell (works on Windows without WSL). Interpolated values are escaped, so $\ls ${userInput}`is injection-safe. Use.quiet()to suppress output,.nothrow()` to not throw on non-zero exit.

Embedded SQLite

import { Database } from "bun:sqlite";
const db = new Database("app.db");
const rows = db.query("SELECT * FROM users WHERE age > ?").all(18);

Synchronous, built in — no native module to compile. :memory: for an in-memory DB.

Env files

Bun reads .env, .env.local, .env.{NODE_ENV} automatically — no dotenv.config(). Access via process.env.FOO or Bun.env.FOO. Precedence (most → least): .env.local > .env.{NODE_ENV} > .env.

TypeScript

• No tsconfig setup needed to run — Bun resolves and transforms TS on the fly and honours tsconfig.json for paths, JSX, and target.
• Bun does not type-check at runtime. Still run tsc --noEmit (or bun tsc) in CI and rely on your editor.
• Install @types/bun (dev) so Bun.*, bun:*, and $ are typed.

Config: bunfig.toml

Project- and user-level settings live in bunfig.toml (next to package.json). Common keys: a [test] block with preload for setup files and coverageThreshold; [install] registry/scopes; a global preload for instrumentation. Reach for it when a flag needs to apply to every bun invocation.

Single-file executables

bun build ./cli.ts --compile --outfile mycli

--compile bundles your code plus the Bun runtime into a standalone binary — handy for shipping CLIs without a Node install. Add --minify and --target=bun-linux-x64 to cross-compile.

What NOT to do

• Add tsx, ts-node, or a transpile step solely to run TS — Bun runs TS natively.
• Add dotenv — it does nothing useful in Bun.
• Add nodemon — use bun --watch / bun --hot.
• Use vitest/jest for new tests in a Bun project — bun test is faster and built-in. Use Vitest only when you need a feature Bun's runner lacks.
• Import from "vitest" and expect bun test to pick it up — the runner reads "bun:test".
• Mix npm install/pnpm install into a Bun project — the lockfile is bun.lock, and switching managers thrashes deps.
• Reach for Bun.serve()/bun:sqlite/$ in code that must also run on Node — see Portability.

Portability

Bun-specific APIs (Bun.*, $, "bun:..." imports) make code non-portable. Acceptable when:

• The repo is Bun-only by design (CLI tools, scripts, internal services, this repo's validator).
• The Node equivalent is meaningfully worse (e.g. Bun.file streaming, bun:sqlite vs a native module).

Avoid Bun-specific APIs in:

• Library code published to npm for general consumption.
• Code shared between Bun and Cloudflare Workers / Deno / the browser.
• Anywhere a teammate might npm install and expect it to work.

A pragmatic split: scripts and the test runner use Bun APIs freely; portable library/application code stays standards-based. For servers that must run on both, use a standards-based framework (Hono, Elysia) over raw Bun.serve.

Cross-references

• [[vite-expertise]] — Bun as the runtime/package manager under a Vite app.
• [[bundler-expertise]] — bun build as a bundler/target alongside esbuild and friends.
• [[typescript-strict-expertise]] — Bun runs TS at any strictness, so strict: true in tsconfig costs nothing.
• [[effect-services-expertise]] — @effect/platform-bun provides BunFileSystem / BunRuntime, the Bun counterparts to @effect/platform-node.