Bun Runtime
Overview
Bun is an all-in-one JavaScript and TypeScript runtime that includes a fast package manager, bundler, test runner, and Node.js-compatible APIs. It natively executes TypeScript and JSX without a separate compilation step.
When to use: Fast server-side JavaScript, TypeScript-first projects, replacing Node.js for better startup performance, built-in SQLite, password hashing, file I/O, HTTP servers, bundling, and testing without external tooling.
When NOT to use: Projects requiring full Node.js ecosystem compatibility (some native modules unsupported), production environments needing battle-tested stability of Node.js, or browser-only code that does not need a runtime.
Quick Reference
| Pattern |
API |
Key Points |
| HTTP server |
Bun.serve({ routes, fetch }) |
Route-based, static/dynamic routes, per-method handlers |
| File read |
Bun.file(path) |
Lazy BunFile (Blob), .text(), .json(), .stream() |
| File write |
Bun.write(dest, data) |
Accepts string, Blob, Response, BunFile |
| SQLite |
new Database(path) from bun:sqlite |
Synchronous queries, prepared statements, WAL mode |
| Password hash |
Bun.password.hash(pw) |
Argon2id default, bcrypt option, async and sync variants |
| Password verify |
Bun.password.verify(pw, hash) |
Auto-detects algorithm from hash format |
| Bundler |
Bun.build({ entrypoints, outdir }) |
Tree-shaking, code splitting, plugins, multiple targets |
| Test runner |
import { test, expect } from "bun:test" |
Jest-compatible, mocking, snapshots, watch mode |
| Install packages |
bun install |
Fast lockfile resolution, npm-compatible |
| Add package |
bun add <pkg> |
-d for dev, -g for global |
| Run script |
bun run <script> |
Runs package.json scripts or files directly |
| Execute binary |
bunx <pkg> |
Like npx, runs without installing |
| S3 client |
new S3Client(opts) / s3.file(key) |
Built-in S3-compatible storage client |
| HTML imports |
import page from './index.html' |
Fullstack: import HTML as route handler |
Common Mistakes
| Mistake |
Correct Pattern |
Using fetch handler only without routes |
Use routes object for static/dynamic routing (Bun v1.2.3+), fetch as fallback |
Forgetting await on Bun.write() |
Bun.write() is async, always await it |
Using Bun.file(path).text() without await |
.text(), .json(), .arrayBuffer() all return Promises |
| Creating SQLite database without WAL mode |
Enable WAL for concurrent reads: db.exec("PRAGMA journal_mode = WAL") |
Using bun install without --frozen-lockfile in CI |
Use bun install --frozen-lockfile for reproducible CI builds |
Importing jest globals in Bun tests |
Import from bun:test, not @jest/globals or vitest |
Using node_modules/.bin/ directly |
Use bunx or bun run instead of referencing bin paths |
Expecting Bun.build() to throw on failure |
Check result.success boolean, errors are in result.logs |
Using --target node when deploying to Bun |
Use --target bun for Bun-specific optimizations and bytecode |
| Synchronous password hashing in request handlers |
Use await Bun.password.hash() async variant in servers |
Delegation
- Project scaffolding: Use
Explore agent
- Performance profiling: Use
Task agent
- Code review: Delegate to
code-reviewer agent
If the typescript-patterns skill is available, delegate advanced TypeScript typing questions to it.
References
- Runtime APIs: Bun.serve(), Bun.file(), SQLite, password hashing, and utilities
- Package management: install, add, remove, workspaces, lockfile
- Bundler: Bun.build(), entrypoints, plugins, tree-shaking
- Testing: bun:test, assertions, mocking, snapshots, lifecycle hooks
1---2name: bun-runtime3description: Bun JavaScript runtime, bundler, and package manager. Covers Bun.serve() HTTP server, Bun.file() I/O, SQLite, password hashing, Bun.build() bundler, bun:test runner, and package management. Use when building with Bun APIs, running scripts with Bun, bundling code, managing packages with bun install/add, or writing tests with bun:test.4license: MIT5---6
7# Bun Runtime
8
9## Overview
10
11Bun is an all-in-one JavaScript and TypeScript runtime that includes a fast package manager, bundler, test runner, and Node.js-compatible APIs. It natively executes TypeScript and JSX without a separate compilation step.
12
13**When to use:** Fast server-side JavaScript, TypeScript-first projects, replacing Node.js for better startup performance, built-in SQLite, password hashing, file I/O, HTTP servers, bundling, and testing without external tooling.
14
15**When NOT to use:** Projects requiring full Node.js ecosystem compatibility (some native modules unsupported), production environments needing battle-tested stability of Node.js, or browser-only code that does not need a runtime.
16
17## Quick Reference
18
19| Pattern | API | Key Points |
20| ---------------- | ----------------------------------------- | -------------------------------------------------------- |
21| HTTP server | `Bun.serve({ routes, fetch })` | Route-based, static/dynamic routes, per-method handlers |
22| File read | `Bun.file(path)` | Lazy BunFile (Blob), `.text()`, `.json()`, `.stream()` |
23| File write | `Bun.write(dest, data)` | Accepts string, Blob, Response, BunFile |
24| SQLite | `new Database(path)` from `bun:sqlite` | Synchronous queries, prepared statements, WAL mode |
25| Password hash | `Bun.password.hash(pw)` | Argon2id default, bcrypt option, async and sync variants |
26| Password verify | `Bun.password.verify(pw, hash)` | Auto-detects algorithm from hash format |
27| Bundler | `Bun.build({ entrypoints, outdir })` | Tree-shaking, code splitting, plugins, multiple targets |
28| Test runner | `import { test, expect } from "bun:test"` | Jest-compatible, mocking, snapshots, watch mode |
29| Install packages | `bun install` | Fast lockfile resolution, npm-compatible |
30| Add package | `bun add <pkg>` | `-d` for dev, `-g` for global |
31| Run script | `bun run <script>` | Runs package.json scripts or files directly |
32| Execute binary | `bunx <pkg>` | Like npx, runs without installing |
33| S3 client | `new S3Client(opts)` / `s3.file(key)` | Built-in S3-compatible storage client |
34| HTML imports | `import page from './index.html'` | Fullstack: import HTML as route handler |
35
36## Common Mistakes
37
38| Mistake | Correct Pattern |
39| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
40| Using `fetch` handler only without `routes` | Use `routes` object for static/dynamic routing (Bun v1.2.3+), `fetch` as fallback |
41| Forgetting `await` on `Bun.write()` | `Bun.write()` is async, always await it |
42| Using `Bun.file(path).text()` without `await` | `.text()`, `.json()`, `.arrayBuffer()` all return Promises |
43| Creating SQLite database without WAL mode | Enable WAL for concurrent reads: `db.exec("PRAGMA journal_mode = WAL")` |
44| Using `bun install` without `--frozen-lockfile` in CI | Use `bun install --frozen-lockfile` for reproducible CI builds |
45| Importing `jest` globals in Bun tests | Import from `bun:test`, not `@jest/globals` or `vitest` |
46| Using `node_modules/.bin/` directly | Use `bunx` or `bun run` instead of referencing bin paths |
47| Expecting `Bun.build()` to throw on failure | Check `result.success` boolean, errors are in `result.logs` |
48| Using `--target node` when deploying to Bun | Use `--target bun` for Bun-specific optimizations and bytecode |
49| Synchronous password hashing in request handlers | Use `await Bun.password.hash()` async variant in servers |
50
51## Delegation
52
53- **Project scaffolding**: Use `Explore` agent
54- **Performance profiling**: Use `Task` agent
55- **Code review**: Delegate to `code-reviewer` agent
56
57> If the `typescript-patterns` skill is available, delegate advanced TypeScript typing questions to it.
58
59## References
60
61- [Runtime APIs: Bun.serve(), Bun.file(), SQLite, password hashing, and utilities](references/runtime-apis.md)
62- [Package management: install, add, remove, workspaces, lockfile](references/package-management.md)
63- [Bundler: Bun.build(), entrypoints, plugins, tree-shaking](references/bundler.md)
64- [Testing: bun:test, assertions, mocking, snapshots, lifecycle hooks](references/testing.md)
oakoss