local-cal/.ruler/02-BUN-GUIDE.md

Bun Guidelines

CRITICAL: Do not assume you know full Bun APIs. For ANY Bun API you use, confirm them by using bun-docs MCP tools.

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Use bunx <package> <command> instead of npx <package> <command>
• Bun automatically loads .env, so don't use dotenv.

APIs

• Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Bun.sql for Postgres. Don't use pg or postgres.js.
• WebSocket is built-in. Don't use ws.
• Prefer Bun.file over node:fs's readFile/writeFile
• Bun.$ls instead of execa.

Testing

Quick Start

• Run tests: bun test
• Write tests in tests/ folder

Test Structure

• Use describe blocks to group related tests
• Use test for individual test cases
• Use beforeEach/afterEach for setup/teardown

Assertions

• Import: import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
• Common: expect(value).toBe(expected), expect(fn).rejects.toThrow()
• Async: await expect(asyncFn()).resolves.toBe(expected)

Mocking

• Mock functions: mock(fn)
• Mock globals: global.fetch = mock(...)
• Restore mocks in afterEach or finally

Best Practices

• Mock external APIs (fetch, file I/O)
• Test error cases and edge conditions
• Use descriptive test names
• Clean up resources in afterEach

For more information, read the Bun API docs in node_modules/bun-types/docs/**.mdx.