Bun Cheatsheet
A highly-detailed reference for Bun, the fast, all-in-one JavaScript/TypeScript runtime, bundler, package manager, and test runner.
1. CLI Commands
Bun provides a single unified CLI replacing node, npm, npx, and jest/vitest.
# Running scripts & files
bun run index.ts # run a TS/JS file natively
bun run dev # execute scripts defined in package.json
bun x package-name # run a package from bin (replaces npx)
# Managing packages
bun install # install all dependencies
bun add package-name # add dependency (replaces npm install)
bun add -d package-name # add devDependency
bun remove package-name # remove dependency
bun update # update packages
2. Fast Package Manager
Bun installs dependencies up to 25x faster than npm/yarn by using a global cache, hardlinks, and optimized system calls.
# Bun uses a binary lockfile (bun.lockb) for super fast parses
bun install --frozen-lockfile # production install (enforces lockfile)
bun pm bin # locate the active node_modules/.bin directory
bun pm cache # show the cache folder path
bun pm cache rm # clear the local/global package cache
3. High-Performance Core APIs
Bun provides blazing fast replacements for standard file, network, and security operations.
Fast HTTP Server (Bun.serve)
Bun.serve({
port: 3000,
fetch(req) {
const url = new URL(req.url);
if (url.pathname === "/") {
return new Response("Welcome to Bun!");
}
if (url.pathname === "/api") {
return Response.json({ status: "ok", version: Bun.version });
}
return new Response("Not Found", { status: 404 });
},
error(error) {
return new Response(`Error occurred: ${error.message}`, { status: 500 });
},
});
console.log("Server running on http://localhost:3000");
High-Speed File I/O (Bun.file)
// 1. Reading files efficiently
const file = Bun.file("data.json");
const exists = await file.exists();
const text = await file.text();
const json = await file.json(); // Direct parse
// 2. Writing files efficiently
const data = { name: "Bun", speed: "blazing" };
await Bun.write("output.json", JSON.stringify(data, null, 2));
// 3. Streaming and binary content
const binaryStream = file.stream();
const arrayBuffer = await file.arrayBuffer();
Cryptography & Password Hashing
// Fast hashing out of the box
const password = "mysecretpassword";
const hashed = await Bun.password.hash(password);
// Verify hashed password
const isMatch = await Bun.password.verify(password, hashed);
console.log(`Password match: ${isMatch}`);
4. Built-in SQLite Database
Bun comes natively bundled with a highly optimized SQLite driver (bun:sqlite), bypassing slow system-level bindings.
import { Database } from "bun:sqlite";
// Create an in-memory database or load a file
const db = new Database(":memory:"); // or new Database("mydb.sqlite");
// Create table and execute queries
db.run("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)");
// Prepare statement and execute batch operations
const insertUser = db.prepare("INSERT INTO users (name, email) VALUES ($name, $email)");
insertUser.run({ $name: "Jules", $email: "jules@example.com" });
// Retrieve results
const users = db.query("SELECT * FROM users").all();
const singleUser = db.query("SELECT * FROM users WHERE id = ?1").get(1);
console.log("Database entries:", users);
db.close();
5. Bun Shell ($)
Bun Shell allows you to run shell commands inside JavaScript/TypeScript cross-platform (Mac, Linux, Windows) with complete escape safety.
import { $ } from "bun";
// 1. Basic command execution
await $`echo "Hello World"`;
// 2. Redirect stdout into variables
const files = await $`ls -la`.text();
console.log("Files present:", files);
// 3. Multi-line script execution
const branch = "main";
await $`
git checkout ${branch}
git pull origin ${branch}
`;
// 4. Input redirection from variables
const inputData = "Data to process\nMore lines";
const processed = await $`grep "Data"`.map(inputData).text();
6. Native Bundler (Bun.build)
Bun features an incredibly fast JavaScript/TypeScript compiler and bundler.
// build.ts
await Bun.build({
entrypoints: ["./index.ts"],
outdir: "./dist",
target: "browser", // "browser" | "bun" | "node"
minify: true,
sourcemap: "external", // "inline" | "external" | "none"
naming: "[name].[ext]",
});
Execute build via CLI:
bun build ./index.ts --outdir ./dist --minify
7. Bun Test
Bun includes a fully Jest-compatible fast test runner built-in, supporting TS, JSX, mock interfaces, and snapshots.
// math.test.ts
import { expect, test, describe, beforeAll, mock } from "bun:test";
describe("Math Suite", () => {
beforeAll(() => {
console.log("Setting up suite...");
});
test("addition works", () => {
expect(1 + 1).toBe(2);
});
test("object matching", () => {
expect({ a: 1, b: 2 }).toEqual({ a: 1, b: 2 });
});
test("mocking functions", () => {
const double = mock((x: number) => x * 2);
expect(double(2)).toBe(4);
expect(double).toHaveBeenCalledTimes(1);
});
});
Run tests from the CLI:
bun test # run all tests (*.test.ts, *.spec.ts)
bun test --watch # run tests in watcher mode
bun test --coverage # run and generate code coverage report