Bun Development

Navigation hub for Bun guidance focused on production-safe implementation.

When to Apply

Use this skill when:

• You need Bun-native runtime APIs (Bun.file, Bun.write, Bun.serve)
• You are writing or debugging tests with bun test
• You are adding bun:sqlite usage with transactions or prepared statements
• You are setting dependency/workspace policy in a Bun project
• You need deterministic security guardrails for shell/SQL inputs

When Not to Use

• The project standard runtime is strictly Node.js with no Bun support
• You need framework-specific guidance not covered by Bun APIs
• The task is only package-agnostic JavaScript refactoring

Workflow

1. Confirm Bun is available and lock dependency strategy.
2. Choose the category (runtime, file I/O, testing, sqlite, package, security).
3. Implement with copy/paste commands from Quick Commands.
4. Apply anti-pattern checks before finalizing.
   • If bun install fails: check bun.lock/bun.lockb for merge conflicts, resolve them, and re-run bun install.
   • If tests fail after dependency changes: run bun test to isolate regressions before proceeding.
5. Validate behavior with tests or execution checks.
   • If validation fails: revert the last change, confirm the error, and address the specific failure before re-validating.
6. For SQL validation (rg finds non-prepared statements in existing code): refactor each flagged call to use db.prepare(...) with bound parameters before merging; do not leave raw interpolations in place.
7. Document decisions with links to exact references used.

Quick Commands

Verify Runtime

bun --version

Expected: a Bun version is printed.

Install Dependencies

bun install

Expected: lockfile is updated consistently (bun.lock/bun.lockb per project setup).

Run Script

bun run src/index.ts

Expected: script executes without Node.js runtime shims.

Execute Tests

bun test

Expected: failing assertions clearly identify behavior regressions.

Start HTTP Service

bun run server.ts

Expected: service binds configured port and handles requests via Bun.serve.

Validate SQL Pattern

rg -n "query\\(|prepare\\(" src

Expected: queries in new code paths use prepared statements where input is user-controlled. If raw query( calls with interpolated values are found in existing code, refactor them to db.prepare(...) with bound parameters before proceeding.

Categories by Priority

Anti-Patterns

NEVER mix Node.js fs calls into Bun-native file workflows

WHY: mixed APIs create inconsistent behavior and miss Bun performance advantages. BAD: readFileSync("./config.json") for Bun-managed file reads. GOOD: await Bun.file("./config.json").text().

BAD:

import { readFileSync } from "node:fs";
const config = readFileSync("./config.json", "utf8");

GOOD:

const config = await Bun.file("./config.json").text();

NEVER run npm install in Bun-managed repositories

WHY: mixed package managers cause lockfile drift and nondeterministic installs. BAD: npm install GOOD: bun install

NEVER interpolate untrusted input into SQL strings

WHY: direct interpolation can introduce SQL injection vulnerabilities. BAD: interpolate untrusted values into query strings. GOOD: bind values with prepared statements.

BAD:

db.query(`SELECT * FROM users WHERE email = '${email}'`).all();

GOOD:

db.prepare("SELECT * FROM users WHERE email = ?").all(email);

NEVER pass unescaped user input into shell commands

WHY: shell interpolation enables command injection. BAD: await Bun.spawn(["sh", "-c", userInput]).exited. GOOD: use direct API calls or fixed command arguments.

BAD:

await Bun.spawn(["sh", "-c", userInput]).exited;

GOOD:

const safePath = Bun.file(userProvidedPath);
await safePath.text();

Reference Map

• Runtime core: references/runtime-globals.md, references/runtime-http-server.md
• File I/O: references/file-io-patterns.md, references/file-vs-node.md, references/file-glob.md
• Testing: references/testing-bun-test.md, references/testing-matchers.md, references/testing-mocking.md, references/testing-snapshots.md
• SQLite: references/sqlite-basics.md
• Package/workspaces: references/pm-workspaces-agent-instructions.md
• Security: references/runtime-shell.md, references/runtime-password.md

References

• Bun Docs
• Bun File I/O
• Bun Test CLI
• Bun SQLite API