---

name: bun-patterns description: Bun package manager and runtime best practices

Bun Patterns

Purpose: Efficient use of Bun as package manager and JavaScript runtime

• Keywords: bun, bun.lockb, bunfig.toml, package manager, dependencies, runtime, Bun.file, Bun.write

Quick Reference

Package Management

Copy# ✅ Use package manager (gets latest)
bun add zod
bun add -d @types/node
bun add --exact react@19.2.0  # Lock version

# ❌ Never manually edit package.json
# (AI training data outdated)

Maintenance:

• bun outdated - Check weekly
• bun audit - Security monthly
• bun pm ls <pkg> - Why installed?

Bun-Specific APIs

Node.js Imports

Copy// ✅ ALWAYS use node: protocol
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'

// ❌ Never omit protocol
import { readFileSync } from 'fs'  // Bad

Why: Clarity, Biome compliance, differentiation from npm packages

File I/O (2-5x faster than Node.js)

Pattern:

Copy// ❌ Node.js fs (slow, sync)
import { readFileSync, writeFileSync } from 'node:fs'
const content = readFileSync('data.json', 'utf-8')
const data = JSON.parse(content)

// ✅ Bun native (fast, async)
const data = await Bun.file('data.json').json()
await Bun.write('output.json', JSON.stringify(data))
if (await Bun.file('config.json').exists()) { /* ... */ }

Glob pattern:

Copy// ❌ readdirSync + statSync (many syscalls)
const entries = readdirSync('skills')
for (const entry of entries) {
  const stats = statSync(join('skills', entry))
  // ...
}

// ✅ Bun.Glob (pattern-based, fast)
const glob = new Bun.Glob('*/SKILL.md')
for (const file of glob.scanSync({ cwd: 'skills' })) {
  const dirName = file.split('/')[0]
}

Performance

Top-level regex (created once vs every call):

Copy// ❌ Regex in function (recreated each call)
function extractTopic(fileName: string) {
  return fileName.replace(/\.md$/, '')
}

// ✅ Top-level (compiled once)
const MD_REGEX = /\.md$/
function extractTopic(fileName: string) {
  return fileName.replace(MD_REGEX, '')
}

Other APIs

Copy// Password hashing
const hash = await Bun.password.hash("pwd")
const valid = await Bun.password.verify("pwd", hash)

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

// Env vars (auto-loads .env)
const key = process.env.API_KEY

Testing

Copyimport { describe, it, expect } from "bun:test"

describe("math", () => {
  it("adds", () => {
    expect(1 + 1).toBe(2)
  })
})

Copybun test           # Run tests
bun test --watch   # Watch mode
bun test --coverage

Scripts

Copy{
  "scripts": {
    "dev": "bun --hot src/index.ts",
    "build": "bun build src/index.ts --outdir ./dist",
    "test": "bun test",
    "typecheck": "tsc --noEmit"
  }
}

Workspaces

Copy{
  "workspaces": ["packages/*", "apps/*"]
}

Copybun install  # All workspaces
bun run --filter @myapp/web dev

Migration

Copy# Remove old lockfiles
rm package-lock.json yarn.lock pnpm-lock.yaml

# Generate bun.lockb
bun install

# Commit
git add bun.lockb

Config (bunfig.toml)

Copy[install]
production = false
registry = "https://registry.npmjs.org/"

[install.scopes]
"@myorg" = { url = "https://registry.myorg.com" }

Common Issues

Binary packages:

Copybun install --backend=hardlink

Legacy scripts:

Copy{
  "scripts": {
    "build": "bun run build:app",
    "legacy": "npm run old-script"
  }
}

Docs

• Bun Docs
• Runtime APIs
• Test Runner