bun

Files (7)

• SKILL.md
• bun-advanced.md · references/
• bun-deployment.md · references/
• bun-ecosystem.md · references/
• bun-essentials.md · references/
• bun-fundamentals.md · references/
• bun-tooling.md · references/

SKILL.md (first lines)

# Bun

## Purpose
Build TypeScript/JavaScript services and tooling on Bun, using its built-in server, SQLite driver, file APIs, shell, test runner and bundler where they simplify the stack, while staying aware of where Node.js compatibility still matters.

## Agent Protocol

### Trigger
Exact user phrases: "bun", "bun runtime", "bun install", "bun test", "bun build", "Bun.serve", "bun:sqlite", "Bun.file", "Bun shell", "bun --compile".

### Input Context
- Target: API server, CLI tool, scripts, or library.
- Framework on top of Bun (none, Elysia, Hono, Express via Node compatibility).
- Database (bun:sqlite, PostgreSQL via `Bun.sql` or `postgres`/`pg`, Redis).
- Deployment target (Docker, single binary, serverless).

### Output Artifact
Project layout, server/test/build code and `package.json` scripts. No files unless requested.

### Response Format
```
Runtime: Bun {version}   Framework: {none|Elysia|Hono|Express}
Server: Bun.serve {routes|fetch}   DB: {bun:sqlite|Bun.sql|other}
Scripts: dev/test/build/compile
Code: {files}
Node-compat risks: {native addons, unsupported node: APIs}
```

## Runtime Choice

| Criterion | Bun | Node.js | Deno |
|---|---|---|---|
| TypeScript | Runs `.ts` directly (transpile only, no type-check) | Type stripping built in since Node 22.18/23.6 for erasable syntax; otherwise tsx/build step | Runs `.ts` directly; `deno check` type-checks |
| npm packages | High compatibility; native addons and some `node:` APIs can still differ | Reference implementation | npm via `npm:` specifiers |
| Built-ins | HTTP server, WebSocket, SQLite, Postgres client, S3 client, password hashing, shell, test runner, bundler | Test runner, `node:sqlite` (newer versions) | HTTP, KV, test runner, formatter, linter |
| Maturity | Youngest; verify critical dependencies | Most mature, widest hosting support | Mature, strong permissions model |

Decision: choose Bun when its built-ins remove dependencies and your dependency set is verified to work; keep Node.js when you rely on native addons, APM agents or hosting that only supports Node. Always type-check separately (`tsc --noEmit`) because Bun does not.

Startup-time and requests-per-second comparisons vary by benchmark and version; measure on your own workload rather than quoting published numbers.

## Workflow

### Step 1: Project Initialization

```bash
bun init -y                 # package.json, tsconfig.json, index.ts
bun add zod                 # dependencies (writes text lockfile bun.lock)
bun add -d @types/bun typescript
```

```
my-app/
  src/
    index.ts          # Bun.serve entry
    routes/users.ts
    db/sqlite.ts
  tests/users.test.ts
  bun.lock
  package.json
  tsconfig.json
```

### Step 2: HTTP Server with Bun.serve

Bun 1.2.3+ supports a `routes` table with path parameters; `fetch` handles everything else.

```ts
// src/index.ts
import { createUser, findUserById, findAllUsers } from './db/sqlite';

const server = Bun.serve({
  port: Number(process.env.PORT ?? 3000),
  routes: {
    '/health': () => Response.json({ status: 'ok' }),
    '/api/v1/users': {
      GET: () => Response.json({ data: findAllUsers() }),
      POST: async (req) => {
        const body = (await req.json()) as { name?: string; email?: string };
        if (!body.name || !body.email) {
          return Response.json({ error: 'name and email required' }, { status: 400 });
        }
        return Response.json({ data: createUser(body.name, body.email) }, { status: 201 });
      },
    },
    '/api/v1/users/:id': (req) => {
      const user = findUserById(req.params.id);
      return user ? Response.json({ data: user }) : Response.json({ error: 'not found' }, { status: 404 });
    },
  },
  fetch() {
    return Response.json({ error: 'not found' }, { status: 404 });
  },
  error(err) {
    console.error('unhandled request error', err);
    return Response.json({ error: 'internal error' }, { status: 500 });
  },
});

console.log(`listening on ${server.url}`);
```

### Step 3: bun:sqlite

```ts
// src/db/sqlite.ts
import { Database } from 'bun:sqlite';

export interface User { id: string; name: string; email: string; created_at: string }

const db = new Database(process.env.DB_PATH ?? './data/app.db', { create: true, strict: true });
db.exec('PRAGMA journal_mode = WAL;');
db.exec('PRAGMA foreign_keys = ON;');
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))

From j4flmao/agent-skills, MIT.

More from j4flmao/agent-skills