itechmeat/bun

Bun

All-in-one JavaScript/TypeScript toolkit: runtime, package manager, test runner, bundler.

Quick Navigation

| Topic | Reference | | ------------------ | ------------------------------------ | | Package Manager | references/package-manager.md | | Project Setup | references/project-scaffolding.md | | Development | references/development.md | | Module System | references/module-system.md | | TypeScript & JSX | references/typescript-jsx.md | | Configuration | references/bunfig.md | | HTTP Server | references/http-server.md | | Browser Automation | references/webview.md | | WebSockets | references/websockets.md | | File I/O | references/file-io.md | | SQLite | references/sqlite.md | | S3 Storage | references/s3.md | | Redis | references/redis.md | | Low-Level Network | references/networking-low-level.md | | Fetch API | references/fetch.md | | Shell Scripts | references/shell.md | | Spawn Process | references/spawn.md | | Workers | references/workers.md | | Native FFI | references/native-interop.md | | C/C++ Compile | references/cc.md | | Transpiler | references/transpiler.md | | Plugins | references/plugins.md | | FS Router | references/file-system-router.md | | Environment Vars | references/env.md | | Utilities | references/utilities.md | | Node.js Compat | references/nodejs-compat.md |

When to Use Bun

• Running TypeScript/JSX without build step
• Fast HTTP server with native routing
• Headless browser automation with native input events
• SQLite database (embedded, no deps)
• WebSocket server/client
• S3-compatible storage (AWS, R2, MinIO)
• Redis caching/pub-sub
• Cross-platform shell scripts
• In-process cron scheduling
• Markdown parsing (v1.3.8+)
• Native library calls via FFI

Core Advantages

• 4x faster startup than Node.js
• Native TypeScript/JSX — no tsconfig needed
• ESM + CommonJS — both work seamlessly
• Web APIs built-in — fetch, WebSocket, etc.
• 30x faster installs than npm

Quick Start

# Run TypeScript directly
bun run index.ts

# Install packages
bun install

# Run package.json script
bun run dev

# Execute package binary
bunx cowsay "Hello"

# Run tests
bun test

# Build for production
bun build ./index.ts --outdir ./dist

# Bundle analysis for LLMs (v1.3.8+)
bun build ./index.ts --metafile-md --outdir ./dist

Critical Rules

| Don't | Do | | ---------------------- | ------------------------ | | http.createServer() | Bun.serve() | | fs.readFileSync() | Bun.file().text() | | better-sqlite3 | bun:sqlite | | child_process.exec() | Bun.$ or Bun.spawn() | | dotenv | Built-in .env support |

Release Highlights (1.3.14)

• Bun.Image: built-in image decoding, transforms, and encoding for common formats with no npm dependency or native addon build step.
• Test workflow: the 1.3.13 line improves dependency-aware filtering for changed-file test runs, which matters when you rely on partial local verification.
• Patch-line runtime work: 1.3.13-1.3.14 continues compatibility and performance work on top of the 1.3.12 WebView/cron/Markdown release line.

Release Highlights (1.3.12)

• Bun.WebView: native headless browser automation with WebKit on macOS and Chrome/Chromium via CDP on all platforms.
• Bun.cron() callback mode: in-process scheduler with no-overlap execution, UTC semantics, hot-reload cleanup, and Disposable job handles.
• Markdown in terminal: bun ./file.md and Bun.markdown.ansi() make terminal-native rendering a first-class workflow.
• Networking/runtime: UDP error/truncation handling, Node-compatible unix-socket lifecycle, proxy tunnel reuse, and Bun.serve() accept/perf improvements.

Essential Recipes

HTTP Server

Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/api/data") {
      return Response.json({ ok: true });
    }
    return new Response("Not Found", { status: 404 });
  },
});

File Operations

// Read
const content = await Bun.file("data.txt").text();

// Write
await Bun.write("output.txt", "Hello World");

// JSON
const config = await Bun.file("config.json").json();

SQLite

import { Database } from "bun:sqlite";

const db = new Database("app.db");
db.run("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");

const insert = db.prepare("INSERT INTO users (name) VALUES (?)");
insert.run("Alice");

const users = db.query("SELECT * FROM users").all();

WebSocket Server

Bun.serve({
  fetch(req, server) {
    if (server.upgrade(req)) return;
    return new Response("Upgrade failed", { status: 400 });
  },
  websocket: {
    message(ws, message) {
      ws.send(`Echo: ${message}`);
    },
  },
});

Shell Commands

import { $ } from "bun";

// Simple command
const files = await $`ls -la`.text();

// With variables (auto-escaped)
const name = "my file.txt";
await $`cat ${name}`;

// Piping
await $`cat data.csv | grep "pattern" | wc -l`;

S3 Storage

import { s3 } from "bun";

// Upload
await s3.file("uploads/doc.pdf").write(data);

// Download
const content = await s3.file("uploads/doc.pdf").text();

// Presigned URL
const url = s3.presign("uploads/doc.pdf", { expiresIn: 3600 });

Redis

import { redis } from "bun";

await redis.set("key", "value");
const value = await redis.get("key");
await redis.expire("key", 3600);

Testing

import { expect, test, describe } from "bun:test";

describe("math", () => {
  test("2 + 2 = 4", () => {
    expect(2 + 2).toBe(4);
  });
});

Configuration (bunfig.toml)

[run]
watch = true

[install]
registry = "https://registry.npmjs.org"

[test]
coverage = true

Environment Variables

# .env files loaded automatically
DATABASE_URL=postgres://localhost/mydb

// Access
Bun.env.DATABASE_URL;
process.env.DATABASE_URL;
import.meta.env.DATABASE_URL;

Links

• Documentation
• Releases
• GitHub
• Discord