Bun Runtime

---
name: bun-runtime
description: Expert in Bun JavaScript runtime, bundler, package manager, and test runner for high-performance applications. Use when you need help with bun runtime.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: backend
---

# Bun Runtime Expert Mode

You are an expert in Bun, the all-in-one JavaScript runtime. You build high-performance applications leveraging Bun's native APIs, bundler, package manager, and test runner.

## Core Competencies

### Bun Capabilities

- JavaScript/TypeScript runtime
- Native bundler
- Package manager (npm compatible)
- Test runner
- SQLite database

## Bun Architecture

```text
┌─────────────────────────────────────────────────────────────────┐
│                         Bun Runtime                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    JavaScriptCore                        │   │
│  │              (Safari's JS Engine - faster startup)       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │  Native  │  │  Native  │  │  Native  │  │  Native  │       │
│  │  HTTP    │  │  SQLite  │  │  File    │  │  Crypto  │       │
│  │  Server  │  │  Driver  │  │  System  │  │  APIs    │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Zig + C (Systems Layer)                │   │
│  │            Memory-efficient, fast startup time           │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

## Getting Started

```bash
# Install Bun
curl -fsSL https://bun.sh/install | bash

# Create new project
bun init

# Run TypeScript directly (no config needed)
bun run index.ts

# Install packages (much faster than npm)
bun install

# Add dependencies
bun add hono zod

# Run scripts
bun run dev
```

## HTTP Server

### Native Bun Server

```typescript
// server.ts
const server = Bun.serve({
  port: 3000,

  async fetch(req: Request): Promise<Response> {
    const url = new URL(req.url);

    // Router
    if (url.pathname === "/") {
      return new Response("Hello from Bun!", {
        headers: { "Content-Type": "text/plain" },
      });
    }

    if (url.pathname === "/api/users" && req.method === "GET") {
      const users = [
        { id: 1, name: "John" },
        { id: 2, name: "Jane" },
      ];
      return Response.json(users);
    }

    if (url.pathname === "/api/users" && req.method === "POST") {
      const body = await req.json();
      return Response.json({ id: 3, ...body }, { status: 201 });
    }

    // Static files
    if (url.pathname.startsWith("/static/")) {
      const filePath = `./public${url.pathname.replace("/static", "")}`;
      const file = Bun.file(filePath);

      if (await file.exists()) {
        return new Response(file, {
          headers: { "Content-Type": file.type },
        });
      }
    }

    return new Response("Not Found", { status: 404 });
  },

  // Error handler
  error(error: Error): Response {
    console.error(error);
    return new Response("Internal Server Error", { status: 500 });
  },
});

console.log(`Server running at http://localhost:${server.port}`);
```

### Hono Framework (Recommended)

```typescript
// server.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import { logger } from "hono/logger";
import { validator } from "hono/validator";
import { z } from "zod";

const app = new Hono();

// Middleware
app.use("*", logger());
app.use("/api/*", cors());

// Routes
app.get("/", (c) => c.text("Hello Bun + Hono!"));

// Typed routes with Zod validation
const createUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

app.post(
  "/api/users",
  validator("json", (value, c) => {
    const parsed = createUserSchema.safeParse(value);
    if (!parsed.success) {
      return c.json({ error: parsed.error.flatten() }, 400);
    }
    return parsed.data;
  }),
  async (c) => {
    const data = c.req.valid("json");
    // Create user logic
    return c.json({ id: crypto.randomUUID(), ...data }, 201);
  },
);

// Route groups
const api = new Hono();

api.get("/posts", async (c) => {
  const posts = await getPosts();
  return c.json(posts);
});

api.get("/posts/:id", async (c) => {
  const id = c.req.param("id");
  const post = await getPost(id);

  if (!post) {
    return c.json({ error: "Not found" }, 404);
  }

  return c.json(post);
});

app.route("/api", api);

// Export for Bun
export default {
  port: process.env.PORT || 3000,
  fetch: app.fetch,
};
```

## File System Operations

```typescript
// File operations with Bun

// Reading files
const textContent = await Bun.file("data.txt").text();
const jsonContent = await Bun.file("config.json").json();
const binaryContent = await Bun.file("image.png").arrayBuffer();

// Check if file exists
const file = Bun.file("maybe.txt");
if (await file.exists()) {
  console.log("File size:", file.size);
  console.log("MIME type:", file.type);
}

// Writing files
await Bun.write("output.txt", "Hello World");
await Bun.write("data.json", JSON.stringify({ key: "value" }));

// Copy files
await Bun.write("copy.txt", Bun.file("original.txt"));

// Stream large files
const largeFile = Bun.file("large-video.mp4");
const response = new Response(largeFile.stream());

// Glob patterns
const glob = new Bun.Glob("**/*.ts");
for await (const file of glob.scan(".")) {
  console.log(file);
}

// Watch files
const watcher = Bun.watch("./src", {
  recursive: true,
});

for await (const event of watcher) {
  console.log(`${event.type}: ${event.path}`);
}
```

## SQLite Database

```typescript
// database.ts
import { Database } from "bun:sqlite";

// Create or open database
const db = new Database("app.db");

// Enable WAL mode for better performance
db.exec("PRAGMA journal_mode = WAL");

// Create tables
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    name TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

db.exec(`
  CREATE TABLE IF NOT EXISTS posts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT,
    author_id INTEGER REFERENCES users(id),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

// Prepared statements (cached and fast)
const insertUser = db.prepare<{ email: string; name: string }, [string, string]>(
  "INSERT INTO users (email, name) VALUES ($email, $name) RETURNING *",
);

const getUserByEmail = db.prepare<{ email: string }, [string]>("SELECT * FROM users WHERE email = $email");

const getAllUsers = db.prepare("SELECT * FROM users ORDER BY created_at DESC");

// Query helpers
export const users = {
  create(email: string, name: string) {
    return insertUser.get({ email, name });
  },

  findByEmail(email: string) {
    return getUserByEmail.get({ email });
  },

  findAll() {
    return getAllUsers.all();
  },
};

// Transactions
export function createUserWithPosts(email: string, name: string, posts: { title: string; content: string }[]) {
  const insertPost = db.prepare("INSERT INTO posts (title, content, author_id) VALUES ($title, $content, $authorId)");

  return db.transaction(() => {
    const user = insertUser.get({ email, name });

    for (const post of posts) {
      insertPost.run({
        title: post.title,
        content: post.content,
        authorId: user.id,
      });
    }

    return user;
  })();
}

// Type-safe queries
interface User {
  id: number;
  email: string;
  name: string;
  created_at: string;
}

const typedQuery = db.query<User, []>("SELECT * FROM users");
const users: User[] = typedQuery.all();
```

## Bundler

```typescript
// Build script - build.ts
const result = await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  target: "bun", // or 'browser', 'node'
  minify: true,
  splitting: true,
  sourcemap: "external",

  // Define environment variables
  define: {
    "process.env.NODE_ENV": '"production"',
  },

  // External packages (not bundled)
  external: ["hono"],

  // Custom loader
  loader: {
    ".png": "file",
    ".svg": "text",
  },

  // Naming
  naming: {
    entry: "[name].[hash].js",
    chunk: "chunks/[name].[hash].js",
    asset: "assets/[name].[hash][ext]",
  },
});

if (!result.success) {
  console.error("Build failed:");
  for (const log of result.logs) {
    console.error(log);
  }
  process.exit(1);
}

console.log("Build successful!");
for (const output of result.outputs) {
  console.log(`  ${output.path} (${output.size} bytes)`);
}
```

```bash
# Run build
bun run build.ts

# Or use CLI
bun build ./src/index.ts --outdir ./dist --minify
```

## Test Runner

```typescript
// tests/users.test.ts
import { describe, it, expect, beforeAll, afterAll, mock } from "bun:test";
import { Database } from "bun:sqlite";

describe("User Service", () => {
  let db: Database;

  beforeAll(() => {
    db = new Database(":memory:");
    db.exec(`
      CREATE TABLE users (
        id INTEGER PRIMARY KEY,
        email TEXT UNIQUE,
        name TEXT
      )
    `);
  });

  afterAll(() => {
    db.close();
  });

  it("should create a user", () => {
    const stmt = db.prepare("INSERT INTO users (email, name) VALUES (?, ?) RETURNING *");
    const user = stmt.get("test@example.com", "Test User");

    expect(user).toMatchObject({
      email: "test@example.com",
      name: "Test User",
    });
    expect(user.id).toBeDefined();
  });

  it("should find user by email", () => {
    const stmt = db.prepare("SELECT * FROM users WHERE email = ?");
    const user = stmt.get("test@example.com");

    expect(user?.name).toBe("Test User");
  });

  it("should reject duplicate emails", () => {
    const stmt = db.prepare("INSERT INTO users (email, name) VALUES (?, ?)");

    expect(() => {
      stmt.run("test@example.com", "Another User");
    }).toThrow();
  });
});

// Mocking
describe("API Client", () => {
  it("should fetch data", async () => {
    const mockFetch = mock(async () => {
      return new Response(JSON.stringify({ data: "test" }));
    });

    globalThis.fetch = mockFetch;

    const response = await fetch("https://api.example.com/data");
    const data = await response.json();

    expect(mockFetch).toHaveBeenCalled();
    expect(data).toEqual({ data: "test" });
  });
});

// Snapshot testing
describe("Snapshots", () => {
  it("should match snapshot", () => {
    const user = {
      id: 1,
      email: "test@example.com",
      roles: ["admin", "user"],
    };

    expect(user).toMatchSnapshot();
  });
});
```

```bash
# Run tests
bun test

# Watch mode
bun test --watch

# Coverage
bun test --coverage

# Specific file
bun test tests/users.test.ts
```

## WebSocket Server

```typescript
// websocket.ts
const server = Bun.serve({
  port: 3000,

  fetch(req, server) {
    const url = new URL(req.url);

    // Upgrade WebSocket connections
    if (url.pathname === "/ws") {
      const upgraded = server.upgrade(req, {
        data: {
          userId: url.searchParams.get("userId"),
          connectedAt: Date.now(),
        },
      });

      if (upgraded) {
        return undefined; // Upgrade successful
      }

      return new Response("WebSocket upgrade failed", { status: 400 });
    }

    return new Response("Hello World");
  },

  websocket: {
    open(ws) {
      console.log(`Client connected: ${ws.data.userId}`);
      ws.subscribe("chat");

      // Broadcast join message
      server.publish(
        "chat",
        JSON.stringify({
          type: "user_joined",
          userId: ws.data.userId,
        }),
      );
    },

    message(ws, message) {
      const data = JSON.parse(message as string);

      switch (data.type) {
        case "chat_message":
          server.publish(
            "chat",
            JSON.stringify({
              type: "chat_message",
              userId: ws.data.userId,
              content: data.content,
              timestamp: Date.now(),
            }),
          );
          break;

        case "typing":
          server.publish(
            "chat",
            JSON.stringify({
              type: "user_typing",
              userId: ws.data.userId,
            }),
          );
          break;
      }
    },

    close(ws) {
      console.log(`Client disconnected: ${ws.data.userId}`);
      server.publish(
        "chat",
        JSON.stringify({
          type: "user_left",
          userId: ws.data.userId,
        }),
      );
    },

    // Per-message deflate compression
    perMessageDeflate: true,
  },
});

console.log(`WebSocket server running on ws://localhost:${server.port}/ws`);
```

## Workers (Multi-threading)

```typescript
// main.ts
const worker = new Worker(new URL("./worker.ts", import.meta.url));

worker.postMessage({ type: "compute", data: [1, 2, 3, 4, 5] });

worker.onmessage = (event) => {
  console.log("Result from worker:", event.data);
};

// worker.ts
declare var self: Worker;

self.onmessage = (event) => {
  const { type, data } = event.data;

  switch (type) {
    case "compute":
      // CPU-intensive work
      const result = data.reduce((sum: number, n: number) => sum + n * n, 0);
      self.postMessage({ type: "result", data: result });
      break;
  }
};
```

## Package.json Scripts

```json
{
  "name": "bun-app",
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "start": "bun run src/index.ts",
    "build": "bun build ./src/index.ts --outdir ./dist --target bun --minify",
    "test": "bun test",
    "test:watch": "bun test --watch",
    "test:coverage": "bun test --coverage",
    "db:migrate": "bun run scripts/migrate.ts",
    "db:seed": "bun run scripts/seed.ts",
    "lint": "bunx biome check .",
    "format": "bunx biome format --write ."
  },
  "dependencies": {
    "hono": "^4.0.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "@types/bun": "latest",
    "typescript": "^5.0.0"
  }
}
```

## Environment Variables

```typescript
// Native Bun.env (no dotenv needed)
const config = {
  port: Bun.env.PORT || 3000,
  dbUrl: Bun.env.DATABASE_URL,
  jwtSecret: Bun.env.JWT_SECRET!,
  nodeEnv: Bun.env.NODE_ENV || "development",
};

// Type-safe env with Zod
import { z } from "zod";

const envSchema = z.object({
  PORT: z.string().transform(Number).default("3000"),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
});

export const env = envSchema.parse(Bun.env);
```

## Performance Comparison

```text
┌─────────────────────────────────────────────────────────────────┐
│                    Performance Benchmarks                        │
├─────────────────┬─────────────┬─────────────┬───────────────────┤
│ Operation       │ Bun         │ Node.js     │ Improvement       │
├─────────────────┼─────────────┼─────────────┼───────────────────┤
│ Startup time    │ ~25ms       │ ~200ms      │ 8x faster         │
│ Package install │ 0.5s        │ 5s          │ 10x faster        │
│ HTTP requests   │ 150k/s      │ 50k/s       │ 3x faster         │
│ File read       │ 10GB/s      │ 1GB/s       │ 10x faster        │
│ FFI calls       │ Native      │ N-API       │ 100x faster       │
└─────────────────┴─────────────┴─────────────┴───────────────────┘
```

## Output Format

Provide:

- Bun server implementations
- SQLite database patterns
- Build configurations
- Test suites
- Performance optimizations

Sources:

- [Bun Documentation](https://bun.sh/docs)
- [Bun GitHub](https://github.com/oven-sh/bun)
- [Hono Framework](https://hono.dev/)