CLAUDE.md for Bun Projects

Why Bun Needs Rules That Use Its Built-In Tools

Bun is an all-in-one JavaScript runtime — it includes a package manager (bun install), bundler (Bun.build), test runner (bun:test), HTTP server (Bun.serve), and native SQLite database. AI assistants ignore all of these, generating Node.js patterns: npm install for packages, webpack/esbuild for bundling, Jest for testing, Express for HTTP, and better-sqlite3 for SQLite. Each missed built-in adds unnecessary dependencies, configuration, and startup time.

Bun is designed for speed — it's written in Zig, uses JavaScriptCore (not V8), and optimizes for startup time and throughput. But AI that generates Node-compatible code instead of Bun-native code gets Node-level performance on a Bun runtime — you carry the weight of external packages without leveraging Bun's built-in optimizations.

These rules target Bun 1.1+ and cover: when to use Bun-native APIs vs Node compatibility, the built-in tools, and patterns that maximize Bun's performance advantages.

Rule 1: Bun.serve for HTTP — No Express Needed

The rule: 'Use Bun.serve for HTTP servers: Bun.serve({ port: 3000, fetch(request) { return new Response("Hello"); } }). Bun.serve is the fastest HTTP server in the JavaScript ecosystem — built into the runtime with zero dependencies. Use Web Standard Request/Response. For routing, use Hono (jsr:@hono/hono) or Elysia — frameworks designed for Bun's performance.'

For Elysia: 'Elysia is Bun's native web framework — optimized for Bun's internals: new Elysia().get("/users/:id", ({ params: { id } }) => getUser(id)).listen(3000). It provides: type-safe routing, schema validation (like Fastify), and end-to-end type safety (like tRPC). If you want a framework on Bun, Elysia is purpose-built; Hono is multi-runtime.'

AI generates const app = express(); app.listen(3000) in Bun projects. Express works on Bun (Node compatibility) but: adds 2MB of dependencies, uses Node's HTTP server (not Bun.serve), and misses Bun's optimized fetch handler. Bun.serve with Hono or Elysia is faster, smaller, and Bun-native.

• Bun.serve: built-in, fastest JS HTTP server — Web Standard Request/Response
• Elysia: Bun-native framework — type-safe routing, schema validation
• Hono: multi-runtime (Bun, Deno, Workers, Node) — works great on Bun
• Express works (Node compat) but misses Bun.serve optimizations
• No node:http or http.createServer — Bun.serve is the native HTTP

Rule 2: bun:test — No Jest Installation Needed

The rule: 'Use bun:test for all testing: import { test, expect, describe, beforeEach, mock } from "bun:test". The API is Jest-compatible — describe, test/it, expect, beforeEach/afterEach, mock/spyOn. Run with: bun test. No installation, no configuration, no jest.config.ts. Bun's test runner is 10-20x faster than Jest because it doesn't need transpilation or module transformation.'

For mocking: 'Use bun:test mock: const fn = mock(() => 42); expect(fn).toHaveBeenCalled(). Use mock.module for module mocking: mock.module("./api", () => ({ fetchUser: mock(() => testUser) })). Spies: const spy = spyOn(object, "method"). The API matches Jest — existing Jest muscle memory transfers directly.'

For snapshot testing: 'bun:test supports snapshots: expect(result).toMatchSnapshot(). Snapshot files are stored alongside test files. Update with: bun test --update-snapshots. Use sparingly (same rules as Jest snapshots — only for stable, small output).'

Rule 3: Bun.build — No Webpack/esbuild Configuration

The rule: 'Use Bun.build for bundling: await Bun.build({ entrypoints: ["./src/index.ts"], outdir: "./dist", target: "browser", minify: true }). Or from CLI: bun build ./src/index.ts --outdir ./dist --minify. Bun.build handles: TypeScript, JSX, tree-shaking, minification, and source maps — zero config. No webpack.config.js, no esbuild.config.ts, no rollup.config.js.'

For when to use: 'Use Bun.build for: library bundling, CLI tool compilation, simple web app bundling. Use Vite for: React/Vue/Svelte apps that need HMR, plugin ecosystem, and dev server. Bun.build is a bundler, not a dev server — for full development experience with HMR, use Vite with Bun as the runtime (bun --bun vite).'

AI installs webpack + babel + ts-loader for bundling TypeScript in Bun. Bun.build does this natively — one line replaces 50 lines of webpack config and 5 dev dependencies.

Rule 4: Bun-Native APIs

The rule: 'Use Bun's native APIs when they're faster than Node equivalents. Bun.file for file reads (returns a Blob — 10x faster than fs.readFile): const file = Bun.file("data.json"); const content = await file.json(). Bun.write for file writes: await Bun.write("output.txt", data). Bun.sql for native SQLite (built-in, no package): import { Database } from "bun:sqlite"; const db = new Database("app.db").'

For SQLite: 'Bun includes SQLite natively — no better-sqlite3 or sql.js needed: const db = new Database("app.db"); const users = db.query("SELECT * FROM users WHERE active = ?").all(true). It's the same SQLite but with zero-dependency native bindings — faster, smaller, and always available. Use for: local databases, caching, test databases, and embedded data.'

For Node compatibility: 'Bun supports most Node.js APIs: fs, path, crypto, http, net, child_process. Use Node APIs when: no Bun-native alternative exists, or you need compatibility with Node packages. Use Bun APIs when: they exist (Bun.file, Bun.serve, Bun.build, bun:sqlite) — they're faster and designed for Bun's internals.'

• Bun.file: fast file reads returning Blob — .text(), .json(), .arrayBuffer()
• Bun.write: fast file writes — strings, Blobs, Response objects
• bun:sqlite: native SQLite — Database, prepared statements, transactions
• Node APIs available: fs, path, crypto — use when no Bun alternative exists
• Bun APIs preferred: Bun.file > fs.readFile, Bun.serve > http.createServer

Rule 5: bun install and Package Management

The rule: 'Use bun install for package management — it's 10-30x faster than npm/yarn/pnpm. Uses package.json and node_modules (Node-compatible layout). Use bun add package for adding. Use bun remove package for removing. bun.lockb is the binary lockfile — commit it to git. For workspaces: standard package.json workspaces field — bun handles monorepos natively.'

For scripts: 'Use bun run for script execution: bun run dev, bun run build, bun run test. bun run is faster than npm run — it skips the shell overhead. For TypeScript: bun runs .ts files directly — no ts-node, no tsx, no compilation step. bun index.ts just works.'

For bunx: 'Use bunx instead of npx for one-off package execution: bunx prisma migrate dev, bunx create-next-app. bunx is faster because it uses Bun's package resolution — no separate download for cached packages. Drop-in replacement for npx in all contexts.'

Complete Bun Rules Template

Consolidated rules for Bun projects.

• Bun.serve for HTTP — Elysia or Hono for routing — no Express unless Node compat required
• bun:test for testing — Jest-compatible API, 10-20x faster — no installation needed
• Bun.build for bundling — zero config TypeScript + JSX — Vite for dev server with HMR
• Bun.file/Bun.write for fast I/O — bun:sqlite for native SQLite — no external packages
• bun install for packages — bun.lockb committed — bun run for scripts — bunx over npx
• Bun runs .ts directly — no ts-node, no tsx — TypeScript is a first-class citizen
• Node APIs available for compat — Bun APIs preferred when they exist (faster)
• bun --bun vite for Vite with Bun runtime — best of both: Bun speed + Vite DX