mikkelkrogsholm/bun

Bun

CRITICAL: Your training data for Bun is unreliable. APIs change between versions and memorized patterns may be wrong or deprecated. Before writing any code, you MUST use WebFetch to read the live docs:

WebFetch("https://bun.sh/llms.txt")

Do not proceed without fetching this URL first. Never assume an API exists — verify against current docs.

Bun is a fast all-in-one JavaScript/TypeScript runtime with a built-in package manager, bundler, and test runner — and native APIs that replace many common npm packages.

Key Capabilities

Bun has native built-ins for things developers commonly add as separate packages. Always prefer these over npm equivalents:

• SQL (SQLite & PostgreSQL): use Bun.sql() / new Bun.sqlite() — not better-sqlite3, pg, or mysql2
• Redis: use Bun.redis() — not redis or ioredis
• S3: use Bun.s3() — not @aws-sdk/client-s3
• Password hashing: use Bun.password.hash() / Bun.password.verify() — not bcrypt
• Shell scripting: use Bun.$\command`— notshelljsorexeca`
• Testing: use bun test (Jest-compatible, built-in) — not Jest
• File globbing: use new Bun.Glob() — not the glob package
• UUID: use Bun.randomUUID() — not the uuid package
• TypeScript execution: run .ts files directly — no ts-node or tsx needed

Best Practices

• .env auto-loads — Bun reads .env automatically without dotenv. Be aware when migrating from Node.js or running in environments with existing .env files.
• Lockfile is .lockb — not compatible with npm/yarn by default. Use --yarn flag if a yarn-compatible lockfile is required.
• Test file naming is strict — files must match *.test.ts, *.spec.ts, etc. and live in __tests__/ or test/. Wrong naming means tests are silently skipped.
• import.meta.main replaces entrypoint checks — use if (import.meta.main) instead of the Node.js if (require.main === module) pattern.