bun-development

# ⚡ Bun Development > Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by [oven-sh/bun](https://github.com/oven-sh/bun). ## When to Use This Skill Use this skill when: - Starting new JS/TS projects with Bun - Migrating from Node.js to Bun - Optimizing development speed - Using Bun's built-in tools (bundler, test runner) - Troubleshooting Bun-specific issues --- ## 1. Getting Started ### 1.1 Installation ```bash # macOS / Linux curl -fsSL https://bun.sh/install | bash # Windows powershell -c "irm bun.sh/install.ps1 | iex" # Homebrew brew tap oven-sh/bun brew install bun # npm (if needed) npm install -g bun # Upgrade bun upgrade ``` ### 1.2 Why Bun? | Feature | Bun | Node.js | | :-------------- | :------------- | :-------------------------- | | Startup time | ~25ms | ~100ms+ | | Package install | 10-100x faster | Baseline | | TypeScript | Native | Requires transpiler | | JSX | Native | Requires transpiler | | Test runner | Built-in | External (Jest, Vitest) | | Bundler | Built-in | External (Webpack, esbuild) | --- ## 2. Project Setup ### 2.1 Create New Project ```bash # Initialize project bun init # Creates: # ├── package.json # ├── tsconfig.json # ├── index.ts # └── README.md # With specific template bun create <template> <project-name> # Examples bun create react my-app # React app bun create next my-app # Next.js app bun create vite my-app # Vite app bun create elysia my-api # Elysia API ``` ### 2.2 package.json ```json { "name": "my-bun-project", "version": "1.0.0", "module": "index.ts", "type": "module", "scripts": { "dev": "bun run --watch index.ts", "start": "bun run index.ts", "test": "bun test", "build": "bun build ./index.ts --outdir ./dist", "lint": "bunx eslint ." }, "devDependencies": { "@types/bun": "latest" }, "peerDependencies": { "typescript": "^5.0.0" } } ``` ### 2.3 tsconfig.json (Bun-optimized) ```json { "compilerOptions": { "lib": ["ESNext"], "module": "esnext", "target": "esnext", "moduleResolution": "bundler", "moduleDetection": "force", "allowImportingTsExtensions": true, "noEmit": true, "composite": true, "strict": true, "downlevelIteration": true, "skipLibCheck": true, "jsx": "react-jsx", "allowSyntheticDefaultImports": true, "forceConsistentCasingInFileNames": true, "allowJs": true, "types": ["bun-types"] } } ``` --- ## 3. Package Management ### 3.1 Installing Packages ```bash # Install from package.json bun install # or 'bun i' # Add dependencies bun add express # Regular dependency bun add -d typescript # Dev dependency bun add -D @types/node # Dev dependency (alias) bun add --optional pkg # Optional dependency # From specific registry bun add lodash --registry https://registry.npmmirror.com # Install specific version bun add react@18.2.0 bun add react@latest bun add react@next # From git bun add github:user/repo bun add git+https://github.com/user/repo.git ``` ### 3.2 Removing & Updating ```bash # Remove package bun remove lodash # Update packages bun update # Update all bun update lodash # Update specific bun update --latest # Update to latest (ignore ranges) # Check outdated bun outdated ``` ### 3.3 bunx (npx equivalent) ```bash # Execute package binaries bunx prettier --write . bunx tsc --init bunx create-react-app my-app # With specific version bunx -p typescript@4.9 tsc --version # Run without installing bunx cowsay "Hello from Bun!" ``` ### 3.4 Lockfile ```bash # bun.lockb is a binary lockfile (faster parsing) # To generate text lockfile for debugging: bun install --yarn # Creates yarn.lock # Trust existing lockfile bun install --frozen-lockfile ``` --- ## 4. Running Code ### 4.1 Basic Execution ```bash # Run TypeScript directly (no build step!) bun run index.ts # Run JavaScript bun run index.js # Run with arguments bun run server.ts --port 3000 # Run package.json script bun run dev bun run build # Short form (for scripts) bun dev bun build ``` ### 4.2 Watch Mode ```bash # Auto-restart on file changes bun --watch run index.ts # With hot reloading bun --hot run server.ts ``` ### 4.3 Environment Variables ```typescript // .env file is loaded automatically! // Access environment variables const apiKey = Bun.env.API_KEY; const port = Bun.env.PORT ?? "3000"; // Or use process.env (Node.js compatible) const dbUrl = process.env.DATABASE_URL; ``` ```bash # Run with specific env file bun --env-file=.env.production run index.ts ``` --- ## 5. Built-in APIs ### 5.1 File System (Bun.file) ```typescript // Read file const file = Bun.file("./data.json"); const text = await file.text(); const json = await file.json(); const buffer = await file.arrayBuffer(); // File info console.log(file.size); // bytes console.log(file.type); // MIME type // Write file await Bun.write("./output.txt", "Hello, Bun!"); await Bun.write("./data.json", JSON.stringify({ foo: "bar" })); // Stream large files const reader = file.stream(); for await (const chunk of reader) { console.log(chunk); } ``` ### 5.2 HTTP Server (Bun.serve) ```typescript const server = Bun.serve({ port: 3000, fetch(request) { const url = new URL(request.url); if (url.pathname === "/") { return new Response("Hello World!"); } if (url.pathname === "/api/users") { return Response.json([ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, ]); } return new Response("Not Found", { status: 404 }); }, error(error) { return new Response(`Error: ${error.message}`, { status: 500 }); }, }); console.log(`Server running at http://localhost:${server.port}`); ``` ### 5.3 WebSocket Server ```typescript const server = Bun.serve({ port: 3000, fetch(req, server) { // Upgrade to WebSocket if (server.upgrade(req)) { return; // Upgraded } return new Response("Upgrade failed", { status: 500 }); }, websocket: { open(ws) { console.log("Client connected"); ws.send("Welcome!"); }, message(ws, message) { console.log(`Received: ${message}`); ws.send(`Echo: ${message}`); }, close(ws) { console.log("Client disconnected"); }, }, }); ``` ### 5.4 SQLite (Bun.sql) ```typescript import { Database } from "bun:sqlite"; const db = new Database("mydb.sqlite"); // Create table db.run(` CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT UNIQUE ) `); // Insert const insert = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)"); insert.run("Alice", "alice@example.com"); // Query const query = db.prepare("SELECT * FROM users WHERE name = ?"); const user = query.get("Alice"); console.log(user); // { id: 1, name: "Alice", email: "alice@example.com" } // Query all const allUsers = db.query("SELECT * FROM users").all(); ``` ### 5.5 Password Hashing ```typescript // Hash password const password = "super-secret"; const hash = await Bun.password.hash(password); // Verify password const isValid = await Bun.password.verify(password, hash); console.log(isValid); // true // With algorithm options const bcryptHash = await Bun.password.hash(password, { algorithm: "bcrypt", cost: 12, }); ``` --- ## 6. Testing ### 6.1 Basic Tests ```typescript // math.test.ts import { describe, it, expect, beforeAll, afterAll } from "bun:test"; describe("Math operations", () => { it("adds two numbers", () => { expect(1 + 1).toBe(2); }); it("subtracts two numbers", () => { expect(5 - 3).toBe(2); }); }); ``` ### 6.2 Running Tests ```bash # Run all tests bun test # Run specific file bun test math.test.ts # Run matching pattern bun test --grep "adds" # Watch mode bun test --watch # With coverage bun test --coverage # Timeout bun test --timeout 5000 ``` ### 6.3 Matchers ```typescript import { expect, test } from "bun:test"; test("matchers", () => { // Equality expect(1).toBe(1); expect({ a: 1 }).toEqual({ a: 1 }); expect([1, 2]).toContain(1); // Comparisons expect(10).toBeGreaterThan(5); expect(5).toBeLessThanOrEqual(5); // Truthiness expect(true).toBeTruthy(); expect(null).toBeNull(); expect(undefined).toBeUndefined(); // Strings expect("hello").toMatch(/ell/); expect("hello").toContain("ell"); // Arrays expect([1, 2, 3]).toHaveLength(3); // Exceptions expect(() => { throw new Error("fail"); }).toThrow("fail"); // Async await expect(Promise.resolve(1)).resolves.toBe(1); await expect(Promise.reject("err")).rejects.toBe("err"); }); ``` ### 6.4 Mocking ```typescript import { mock, spyOn } from "bun:test"; // Mock function const mockFn = mock((x: number) => x * 2); mockFn(5); expect(mockFn).toHaveBeenCalled(); expect(mockFn).toHaveBeenCalledWith(5);