bun-runtime-expert · diff
git:20260523.3d2d388 to git:20260612.8b09a53
1 added, 5 removed. Audit C to C.
---
name: bun-runtime-expert
description: "Expert skill for the Bun JavaScript/TypeScript runtime. Use when building, testing, or deploying applications with Bun, migrating from Node.js, or leveraging Bun's built-in APIs (Bun.serve, Bun.sql, Bun.s3, bun:test)."
author: "Roedy Rustam"
- github: "https://github.com/roedyrustam/vibes-plug"
- risk: safe
- source: community
- date_added: "2026-05-24"
---
# Bun Runtime Expert
Expert-level guidance for building high-performance applications with the Bun JavaScript/TypeScript runtime (v1.3+). Covers Bun's built-in HTTP server, database clients, bundler, test runner, package manager, and Node.js migration strategies.
- ## When to Use
+ ## Kondisi Pemicu
- Use when scaffolding a new project with Bun as the runtime.
- Use when building HTTP servers or APIs with `Bun.serve()`.
- Use when querying databases with `Bun.sql` (PostgreSQL, MySQL, SQLite).
- Use when interacting with S3-compatible object storage via `Bun.s3`.
- Use when bundling frontend or backend code with `bun build`.
- Use when writing tests with `bun:test`.
- Use when migrating an existing Node.js project to Bun.
- Use when optimizing package installation speed or lockfile management.
---
## Core Architecture
### Why Bun?
Bun is a batteries-included JavaScript/TypeScript runtime that replaces Node.js, npm, Webpack/Vite, and Jest in a single binary:
| Capability | Bun Built-in | Node.js Equivalent |
|---|---|---|
| Runtime | `bun run` | `node` |
| Package Manager | `bun install` | `npm` / `pnpm` / `yarn` |
| Bundler | `bun build` | Webpack / Vite / esbuild |
| Test Runner | `bun test` | Jest / Vitest |
| HTTP Server | `Bun.serve()` | Express / Fastify |
| SQL Client | `Bun.sql` | `pg` / `mysql2` / `better-sqlite3` |
| S3 Client | `Bun.s3` | `@aws-sdk/client-s3` |
| Redis Client | Built-in | `ioredis` |
| TypeScript | Native (zero config) | `ts-node` / `tsx` |
| `.env` loading | Native | `dotenv` |
---
## Quick Start
### 1. Install Bun
```bash
# macOS / Linux
curl -fsSL https://bun.sh/install | bash
# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"
# Verify installation
bun --version
```
### 2. Initialize a New Project
```bash
bun init
```
This generates `package.json`, `tsconfig.json`, and an `index.ts` entry point. TypeScript works out of the box with zero configuration.
### 3. Install Dependencies
```bash
# Install all dependencies (10-100x faster than npm)
bun install
# Add a package
bun add hono zod drizzle-orm
# Add dev dependency
bun add -d @types/bun vitest
```
---
## Bun.serve() — High-Performance HTTP Server
`Bun.serve()` is a zero-dependency HTTP server with built-in TLS, WebSocket support, and hot module reloading.
### Basic HTTP Server
```typescript
// server.ts
Bun.serve({
port: 3000,
fetch(req) {
const url = new URL(req.url);
if (url.pathname === '/api/health') {
return Response.json({ status: 'ok', runtime: 'bun' });
}
if (url.pathname === '/api/users' && req.method === 'POST') {
return handleCreateUser(req);
}
return new Response('Not Found', { status: 404 });
},
});
console.log('🚀 Server running at http://localhost:3000');
async function handleCreateUser(req: Request): Promise<Response> {
const body = await req.json();
// validate & persist...
return Response.json({ id: crypto.randomUUID(), ...body }, { status: 201 });
}
```
### WebSocket Server
```typescript
Bun.serve({
port: 3000,
fetch(req, server) {
// Upgrade HTTP to WebSocket
if (server.upgrade(req)) {
return; // Upgrade succeeded
}
return new Response('Upgrade failed', { status: 500 });
},
websocket: {
open(ws) {
console.log('Client connected');
ws.subscribe('chat');
},
message(ws, message) {
// Broadcast to all subscribers
ws.publish('chat', `User: ${message}`);
},
close(ws) {
console.log('Client disconnected');
},
},
});
```
### Using Hono Framework (Recommended for APIs)
```typescript
// server.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';
const app = new Hono();
app.use('/*', cors());
const createUserSchema = z.object({
email: z.string().email(),
name: z.string().min(2),
});
app.get('/api/health', (c) => c.json({ status: 'ok' }));
app.post('/api/users', zValidator('json', createUserSchema), async (c) => {
const data = c.req.valid('json');
// persist user...
return c.json({ id: crypto.randomUUID(), ...data }, 201);
});
export default app; // Bun auto-detects default export as Bun.serve handler
```
---
## Bun.sql — Unified Database Client
Zero-dependency SQL client supporting PostgreSQL, MySQL/MariaDB, and SQLite via tagged template literals.
### PostgreSQL
```typescript
import { sql } from 'bun';
// Connection is automatically configured from DATABASE_URL env var
// or you can pass options explicitly:
// const sql = new Bun.SQL({ url: 'postgres://user:pass@localhost:5432/mydb' });
// Simple query
const users = await sql`SELECT * FROM users WHERE active = ${true}`;
// Insert with returning
const [newUser] = await sql`
INSERT INTO users (email, name)
VALUES (${email}, ${name})
RETURNING *
`;
// Transaction
await sql.begin(async (tx) => {
const [workspace] = await tx`
INSERT INTO workspaces (name, slug) VALUES (${name}, ${slug}) RETURNING *
`;
await tx`
INSERT INTO workspace_members (workspace_id, user_id, role)
VALUES (${workspace.id}, ${userId}, 'admin')
`;
});
```
### SQLite (Embedded)
```typescript
import { Database } from 'bun:sqlite';
const db = new Database('app.db');
// WAL mode for better concurrent read performance
db.run('PRAGMA journal_mode = WAL');
// Prepared statements (fast & safe)
const getUser = db.prepare('SELECT * FROM users WHERE id = ?');
const user = getUser.get(userId);
// Batch insert with transaction
const insertUser = db.prepare('INSERT INTO users (email, name) VALUES (?, ?)');
const insertMany = db.transaction((users: { email: string; name: string }[]) => {
for (const u of users) insertUser.run(u.email, u.name);
});
insertMany([
{ email: 'a@test.com', name: 'Alice' },
{ email: 'b@test.com', name: 'Bob' },
]);
```
---
## Bun.s3 — Object Storage Client
Built-in S3-compatible client for AWS S3, Cloudflare R2, MinIO, and other providers.
```typescript
import { s3 } from 'bun';
// Configure via env: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, S3_BUCKET
// Upload a file
const file = Bun.file('./report.pdf');
await s3.write('reports/2026/q1.pdf', file);
// Download a file
const data = await s3.file('reports/2026/q1.pdf').text();
// Generate presigned URL
const url = s3.presign('reports/2026/q1.pdf', {
expiresIn: 3600, // 1 hour
});
// List objects
const objects = await s3.list({ prefix: 'reports/' });
// Delete
await s3.delete('reports/old.pdf');
```
---
## bun build — Bundler
Bun's built-in bundler replaces Webpack, Vite, and esbuild for most use cases.
### Bundle for Production
```bash
# Bundle a single entry point
bun build ./src/index.ts --outdir ./dist --minify
# Bundle with multiple entry points
bun build ./src/index.ts ./src/worker.ts --outdir ./dist --splitting --minify
# Target browser
bun build ./src/app.tsx --outdir ./public/js --target browser --minify
```
### Programmatic Build API
```typescript
const result = await Bun.build({
entrypoints: ['./src/index.ts'],
outdir: './dist',
target: 'bun', // 'bun' | 'browser' | 'node'
minify: true,
splitting: true,
sourcemap: 'external',
external: ['postgres'], // Don't bundle native modules
});
if (!result.success) {
console.error('Build failed:');
for (const log of result.logs) {
console.error(log);
}
}
```
### HTML Imports (Zero-Config Frontend)
```bash
# Serve an HTML file with auto-bundled JS/CSS
bun ./index.html
```
Bun automatically transpiles, bundles, and serves all referenced `<script>` and `<link>` tags, including React/JSX support.
---
## bun:test — Test Runner
Jest-compatible test runner with native TypeScript support, lifecycle hooks, and snapshot testing.
### Writing Tests
```typescript
// __tests__/math.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
describe('Math utilities', () => {
it('should add numbers correctly', () => {
expect(1 + 2).toBe(3);
});
it('should handle floating point', () => {
expect(0.1 + 0.2).toBeCloseTo(0.3);
});
});
```
### HTTP API Integration Tests
```typescript
// __tests__/api.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
import app from '../src/server';
describe('Users API', () => {
let server: ReturnType<typeof Bun.serve>;
beforeAll(() => {
server = Bun.serve({ port: 0, fetch: app.fetch }); // Random port
});
afterAll(() => {
server.stop();
});
it('POST /api/users should create a user', async () => {
const res = await fetch(`http://localhost:${server.port}/api/users`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email: 'test@example.com', name: 'Test User' }),
});
expect(res.status).toBe(201);
const body = await res.json();
expect(body).toHaveProperty('id');
expect(body.email).toBe('test@example.com');
});
it('GET /api/health should return ok', async () => {
const res = await fetch(`http://localhost:${server.port}/api/health`);
expect(res.status).toBe(200);
const body = await res.json();
expect(body.status).toBe('ok');
});
});
```
### Running Tests
```bash
# Run all tests
bun test
# Run specific file
bun test __tests__/api.test.ts
# Watch mode
bun test --watch
# With coverage
bun test --coverage
# Concurrent tests
bun test --concurrency 4
```
---
## Node.js Migration Guide
### Step-by-Step Migration
1. **Replace runtime:** Change `node` → `bun` in your scripts.
2. **Replace package manager:** Change `npm install` → `bun install`.
3. **Remove unnecessary devDependencies:**
- `typescript` / `ts-node` / `tsx` → Bun handles TypeScript natively.
- `dotenv` → Bun loads `.env` automatically.
- `jest` / `vitest` → Use `bun:test`.
- `esbuild` / `webpack` → Use `bun build`.
- `nodemon` → Use `bun --watch`.
4. **Update `package.json` scripts:**
```json
{
"scripts": {
"dev": "bun --watch src/index.ts",
"start": "bun src/index.ts",
"build": "bun build ./src/index.ts --outdir ./dist --target bun --minify",
"test": "bun test",
"test:watch": "bun test --watch"
}
}
```
5. **Check Node.js API compatibility:** Most `node:*` APIs are supported. Check [bun.sh/docs/runtime/nodejs-apis](https://bun.sh/docs/runtime/nodejs-apis) for the compatibility matrix.
### Common Migration Patterns
```typescript
// Node.js (before)
import express from 'express';
const app = express();
app.get('/health', (req, res) => res.json({ ok: true }));
app.listen(3000);
// Bun (after) — zero dependencies
Bun.serve({
port: 3000,
fetch(req) {
if (new URL(req.url).pathname === '/health') {
return Response.json({ ok: true });
}
return new Response('Not Found', { status: 404 });
},
});
```
```typescript
// Node.js file read (before)
import fs from 'node:fs/promises';
const content = await fs.readFile('./data.json', 'utf-8');
// Bun file read (after) — also supports node:fs
const content = await Bun.file('./data.json').text();
const json = await Bun.file('./data.json').json();
```
---
## Project Structure (Recommended)
```
my-bun-app/
├── src/
│ ├── index.ts # Entry point (Bun.serve or Hono app)
│ ├── routes/ # Route handlers
│ ├── middleware/ # Auth, CORS, rate limiting
│ ├── db/
│ │ ├── schema.ts # Drizzle ORM schema
│ │ ├── migrate.ts # Migration runner
│ │ └── index.ts # Database client (Bun.sql or Drizzle)
│ ├── services/ # Business logic
│ └── utils/ # Shared utilities
├── __tests__/ # bun:test files
├── .env # Environment variables (auto-loaded)
├── bunfig.toml # Bun configuration
├── tsconfig.json # TypeScript config
├── bun.lock # Lockfile (JSONC-based, human-readable)
└── package.json
```
### bunfig.toml Configuration
```toml
[install]
# Use exact versions by default
exact = true
[test]
# Enable coverage by default
coverage = true
coverageDir = "coverage"
[run]
# Auto-reload on file changes in development
watch = true
```
---
## Best Practices
### Performance
- ✅ Use `Bun.serve()` directly or Hono for HTTP — avoid Express (slower compat layer).
- ✅ Use `Bun.sql` with tagged templates for parameterized, injection-safe queries.
- ✅ Use `Bun.file()` for file I/O — it returns a lazy `BunFile` that streams efficiently.
- ✅ Use `bun build --minify --splitting` for production frontend bundles.
- ✅ Use `--watch` flag during development instead of `nodemon`.
### Security
- ✅ Always parameterize queries via template literals in `Bun.sql` (automatically prevents SQL injection).
- ✅ Validate all request bodies with Zod before processing.
- ✅ Use Bun's built-in package security scanner to audit dependencies.
- ❌ Never concatenate user input into SQL strings manually.
### Testing
- ✅ Use `bun:test` — it's Jest-compatible and significantly faster.
- ✅ Use `Bun.serve({ port: 0 })` in tests for random port allocation (prevents port conflicts).
- ✅ Run `bun test --coverage` to track coverage metrics.
---
## Troubleshooting
**Problem:** `bun install` fails with native module compilation errors
**Solution:** Some Node.js native addons (e.g., `bcrypt`, `sharp`) require specific platform binaries. Use `bun add sharp --force` or switch to pure-JS alternatives (`bcryptjs` instead of `bcrypt`).
**Problem:** TypeScript types not recognized for Bun APIs
**Solution:** Add `"types": ["bun-types"]` to your `tsconfig.json` `compilerOptions`, or run `bun add -d @types/bun`.
**Problem:** Module not found errors for `node:*` imports
**Solution:** Bun supports most `node:*` prefixed imports. Check the [compatibility table](https://bun.sh/docs/runtime/nodejs-apis). For unsupported modules, use Bun's native alternatives (e.g., `Bun.file()` instead of `fs`).
**Problem:** Hot reload not working with `--watch`
**Solution:** Ensure you're running `bun --watch src/index.ts` (not `bun run --watch`). The `--watch` flag must come before the file path.
---
## Limitations
- Use this skill only when the task involves the Bun runtime specifically.
- Bun's Node.js compatibility is extensive but not 100%. Always verify critical `node:*` API usage against the official compatibility matrix.
- Some npm packages with native C/C++ bindings may require platform-specific handling.
- Stop and ask for clarification if the user's project has strict Node.js-only requirements.