JasonDocton Bun Patterns
Rules
| Pattern | Do | Don't |
|---|---|---|
| Packages | bun add <pkg> |
manually edit package.json |
| Node imports | node: protocol always |
bare fs, path |
| File I/O | Bun.file(), Bun.write() |
Node.js fs sync methods |
| Globs | new Bun.Glob() |
readdirSync + statSync |
| Regex | top-level const | inline in functions |
Commands
| Task | Command |
|---|---|
| Install all | bun install |
| Add package | bun add <pkg> |
| Add dev | bun add -d <pkg> |
| Exact version | bun add --exact react@19.2.0 |
| Remove | bun remove <pkg> |
| Run script | bun run <script> |
| Execute TS | bun <file.ts> |
| Test | bun test |
| Outdated | bun outdated |
| Why installed | bun pm ls <pkg> |
Node.js → Bun API
| Node.js | Bun Native |
|---|---|
readFileSync(path, 'utf-8') |
await Bun.file(path).text() |
JSON.parse(readFileSync()) |
await Bun.file(path).json() |
writeFileSync(path, data) |
await Bun.write(path, data) |
existsSync(path) |
await Bun.file(path).exists() |
readdirSync() + statSync() |
new Bun.Glob(pattern) |
File I/O
// ✅ Bun native
const data = await Bun.file("data.json").json()
await Bun.write("output.json", JSON.stringify(data))
if (await Bun.file("config.json").exists()) { /* ... */ }
// ❌ Node.js fs
const content = readFileSync("data.json", "utf-8")
const data = JSON.parse(content)
Glob Pattern
// ✅ Bun.Glob
const glob = new Bun.Glob("*/SKILL.md")
for (const file of glob.scanSync({ cwd: "skills" })) {
const dirName = file.split("/")[0]
}
// ❌ readdirSync + statSync (many syscalls)
Node Protocol
// ✅ always use node: protocol
import { readFileSync } from "node:fs"
import { resolve } from "node:path"
// ❌ bare imports
import { readFileSync } from "fs"
Top-Level Regex
// ✅ compiled once
const MD_REGEX = /\.md$/
function extractTopic(fileName: string) {
return fileName.replace(MD_REGEX, "")
}
// ❌ recreated each call
function extractTopic(fileName: string) {
return fileName.replace(/\.md$/, "")
}
Testing
import { describe, it, expect } from "bun:test"
describe("math", () => {
it("adds", () => expect(1 + 1).toBe(2))
})
bun test · bun test --watch · bun test --coverage
Scripts
{
"scripts": {
"dev": "bun --hot src/index.ts",
"build": "bun build src/index.ts --outdir ./dist",
"test": "bun test",
"typecheck": "tsc --noEmit"
}
}
Workspaces
{ "workspaces": ["packages/*", "apps/*"] }
bun install installs all. bun run --filter @myapp/web dev targets one.
Migration from npm/yarn/pnpm
rm package-lock.json yarn.lock pnpm-lock.yaml
bun install
git add bun.lockb
Other APIs
// Password hashing
const hash = await Bun.password.hash("pwd")
const valid = await Bun.password.verify("pwd", hash)
// HTTP server
Bun.serve({ port: 3000, fetch: () => new Response("Hello") })
// Env (auto-loads .env)
const key = process.env.API_KEY
Troubleshooting
Binary packages failing: bun install --backend=hardlink