bun

Bun

Quick Start

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

# Init project
bun init

# Run TypeScript directly
bun run index.ts

# Watch mode (hard restart on change)
bun --watch index.ts

# Hot reload (preserves global state, no restart)
bun --hot server.ts

Package Management

bun install                    # install all deps
bun add express                # add dependency
bun add -d @types/node         # add dev dependency
bun remove lodash              # remove
bun update                     # update all
bun update --latest            # ignore semver ranges
bunx prettier --write .        # execute package binary (npx equivalent)
bun patch express              # patch a dependency in node_modules

Workspaces

// root package.json
{ "workspaces": ["packages/*"] }

// child package.json
{ "dependencies": { "shared": "workspace:*" } }

bun install --filter "pkg-*"   # install filtered workspaces

Environment Variables

.env files auto-loaded in order: .env → .env.$(NODE_ENV) → .env.local

Bun.env.API_KEY       // Bun-native
process.env.API_KEY   // Node.js compat
import.meta.env.API_KEY

bun --env-file=.env.staging run start

HTTP Server

Bun.serve({
  port: 3000,
  routes: {
    "/": new Response("Home"),
    "/users/:id": (req) => Response.json({ id: req.params.id }),
    "/api/posts": {
      GET: () => Response.json([]),
      POST: async (req) => Response.json(await req.json(), { status: 201 }),
    },
    "/api/*": Response.json({ error: "Not found" }, { status: 404 }),
    "/favicon.ico": Bun.file("./favicon.ico"),
  },
  fetch(req) {
    return new Response("Not Found", { status: 404 });
  },
});

WebSocket Upgrade

Bun.serve({
  fetch(req, server) {
    if (server.upgrade(req, { data: { userId: "123" } })) return;
    return new Response("Not a WebSocket", { status: 400 });
  },
  websocket: {
    open(ws) { ws.subscribe("chat"); },
    message(ws, msg) { ws.publish("chat", msg); },
    close(ws) {},
  },
});