---

name: bun-first description: Describes efficient usage of Bun and Bun APIs instead of Node.js (and its APIs)

Bun-First Development

We default to Bun as our JavaScript runtime, package manager, and task runner. Assume Bun is available unless explicitly stated otherwise.

General Principles

• PREFER Bun over Node.js, npm, pnpm, or yarn
• PREFER Bun’s built-in features over third-party tools when available
• PRFER Bun's native APIs (eg for file access, SQL, S3 etc) over Node.js APIs

Package Management

• USE bun install, bun add, bun remove
• AVOID npm, yarn, pnpm
• Prefer Bun-native lockfiles and resolution behavior
• Keep dependencies minimal and intentional

Scripts & Tooling

• PREFER bun run for scripts
• AVOID Bun’s built-in test runner (bun test) => We'll use Vitest for testing
• AVOID Bun’s build tool (bun build) => We'll use Vite
• Avoid introducing extra task runners unless required

Runtime & APIs

• PREFER Bun’s native APIs (fetch, fs, path, env handling)
• Write code assuming modern Web APIs are available in the runtime
• Avoid Node-specific APIs unless explicitly required

Performance & DX

• Prefer simple, explicit scripts over complex toolchains
• AVOID unnecessary abstractions