Bun Development

1---
2name: bun-development
3description: "Modern JavaScript/TypeScript development with Bun runtime. Covers package management, bundling, testing, and migration from Node.js. Use when working with Bun, optimizing JS/TS development speed, or migrating from Node.js to Bun."
4---
5 
6# ⚡ Bun Development
7 
8> Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by [oven-sh/bun](https://github.com/oven-sh/bun).
9 
10## When to Use This Skill
11 
12Use this skill when:
13 
14- Starting new JS/TS projects with Bun
15- Migrating from Node.js to Bun
16- Optimizing development speed
17- Using Bun's built-in tools (bundler, test runner)
18- Troubleshooting Bun-specific issues
19 
20---
21 
22## 1. Getting Started
23 
24### 1.1 Installation
25 
26```bash
27# macOS / Linux
28curl -fsSL https://bun.sh/install | bash
29 
30# Windows
31powershell -c "irm bun.sh/install.ps1 | iex"
32 
33# Homebrew
34brew tap oven-sh/bun
35brew install bun
36 
37# npm (if needed)
38npm install -g bun
39 
40# Upgrade
41bun upgrade
42```
43 
44### 1.2 Why Bun?
45 
46| Feature         | Bun            | Node.js                     |
47| :-------------- | :------------- | :-------------------------- |
48| Startup time    | ~25ms          | ~100ms+                     |
49| Package install | 10-100x faster | Baseline                    |
50| TypeScript      | Native         | Requires transpiler         |
51| JSX             | Native         | Requires transpiler         |
52| Test runner     | Built-in       | External (Jest, Vitest)     |
53| Bundler         | Built-in       | External (Webpack, esbuild) |
54 
55---
56 
57## 2. Project Setup
58 
59### 2.1 Create New Project
60 
61```bash
62# Initialize project
63bun init
64 
65# Creates:
66# ├── package.json
67# ├── tsconfig.json
68# ├── index.ts
69# └── README.md
70 
71# With specific template
72bun create <template> <project-name>
73 
74# Examples
75bun create react my-app        # React app
76bun create next my-app         # Next.js app
77bun create vite my-app         # Vite app
78bun create elysia my-api       # Elysia API
79```
80 
81### 2.2 package.json
82 
83```json
84{
85  "name": "my-bun-project",
86  "version": "1.0.0",
87  "module": "index.ts",
88  "type": "module",
89  "scripts": {
90    "dev": "bun run --watch index.ts",
91    "start": "bun run index.ts",
92    "test": "bun test",
93    "build": "bun build ./index.ts --outdir ./dist",
94    "lint": "bunx eslint ."
95  },
96  "devDependencies": {
97    "@types/bun": "latest"
98  },
99  "peerDependencies": {
100    "typescript": "^5.0.0"
101  }
102}
103```
104 
105### 2.3 tsconfig.json (Bun-optimized)
106 
107```json
108{
109  "compilerOptions": {
110    "lib": ["ESNext"],
111    "module": "esnext",
112    "target": "esnext",
113    "moduleResolution": "bundler",
114    "moduleDetection": "force",
115    "allowImportingTsExtensions": true,
116    "noEmit": true,
117    "composite": true,
118    "strict": true,
119    "downlevelIteration": true,
120    "skipLibCheck": true,
121    "jsx": "react-jsx",
122    "allowSyntheticDefaultImports": true,
123    "forceConsistentCasingInFileNames": true,
124    "allowJs": true,
125    "types": ["bun-types"]
126  }
127}
128```
129 
130---
131 
132## 3. Package Management
133 
134### 3.1 Installing Packages
135 
136```bash
137# Install from package.json
138bun install              # or 'bun i'
139 
140# Add dependencies
141bun add express          # Regular dependency
142bun add -d typescript    # Dev dependency
143bun add -D @types/node   # Dev dependency (alias)
144bun add --optional pkg   # Optional dependency
145 
146# From specific registry
147bun add lodash --registry https://registry.npmmirror.com
148 
149# Install specific version
150bun add react@18.2.0
151bun add react@latest
152bun add react@next
153 
154# From git
155bun add github:user/repo
156bun add git+https://github.com/user/repo.git
157```
158 
159### 3.2 Removing & Updating
160 
161```bash
162# Remove package
163bun remove lodash
164 
165# Update packages
166bun update              # Update all
167bun update lodash       # Update specific
168bun update --latest     # Update to latest (ignore ranges)
169 
170# Check outdated
171bun outdated
172```
173 
174### 3.3 bunx (npx equivalent)
175 
176```bash
177# Execute package binaries
178bunx prettier --write .
179bunx tsc --init
180bunx create-react-app my-app
181 
182# With specific version
183bunx -p typescript@4.9 tsc --version
184 
185# Run without installing
186bunx cowsay "Hello from Bun!"
187```
188 
189### 3.4 Lockfile
190 
191```bash
192# bun.lockb is a binary lockfile (faster parsing)
193# To generate text lockfile for debugging:
194bun install --yarn    # Creates yarn.lock
195 
196# Trust existing lockfile
197bun install --frozen-lockfile
198```
199 
200---
201 
202## 4. Running Code
203 
204### 4.1 Basic Execution
205 
206```bash
207# Run TypeScript directly (no build step!)
208bun run index.ts
209 
210# Run JavaScript
211bun run index.js
212 
213# Run with arguments
214bun run server.ts --port 3000
215 
216# Run package.json script
217bun run dev
218bun run build
219 
220# Short form (for scripts)
221bun dev
222bun build
223```
224 
225### 4.2 Watch Mode
226 
227```bash
228# Auto-restart on file changes
229bun --watch run index.ts
230 
231# With hot reloading
232bun --hot run server.ts
233```
234 
235### 4.3 Environment Variables
236 
237```typescript
238// .env file is loaded automatically!
239 
240// Access environment variables
241const apiKey = Bun.env.API_KEY;
242const port = Bun.env.PORT ?? "3000";
243 
244// Or use process.env (Node.js compatible)
245const dbUrl = process.env.DATABASE_URL;
246```
247 
248```bash
249# Run with specific env file
250bun --env-file=.env.production run index.ts
251```
252 
253---
254 
255## 5. Built-in APIs
256 
257### 5.1 File System (Bun.file)
258 
259```typescript
260// Read file
261const file = Bun.file("./data.json");
262const text = await file.text();
263const json = await file.json();
264const buffer = await file.arrayBuffer();
265 
266// File info
267console.log(file.size); // bytes
268console.log(file.type); // MIME type
269 
270// Write file
271await Bun.write("./output.txt", "Hello, Bun!");
272await Bun.write("./data.json", JSON.stringify({ foo: "bar" }));
273 
274// Stream large files
275const reader = file.stream();
276for await (const chunk of reader) {
277  console.log(chunk);
278}
279```
280 
281### 5.2 HTTP Server (Bun.serve)
282 
283```typescript
284const server = Bun.serve({
285  port: 3000,
286 
287  fetch(request) {
288    const url = new URL(request.url);
289 
290    if (url.pathname === "/") {
291      return new Response("Hello World!");
292    }
293 
294    if (url.pathname === "/api/users") {
295      return Response.json([
296        { id: 1, name: "Alice" },
297        { id: 2, name: "Bob" },
298      ]);
299    }
300 
301    return new Response("Not Found", { status: 404 });
302  },
303 
304  error(error) {
305    return new Response(`Error: ${error.message}`, { status: 500 });
306  },
307});
308 
309console.log(`Server running at http://localhost:${server.port}`);
310```
311 
312### 5.3 WebSocket Server
313 
314```typescript
315const server = Bun.serve({
316  port: 3000,
317 
318  fetch(req, server) {
319    // Upgrade to WebSocket
320    if (server.upgrade(req)) {
321      return; // Upgraded
322    }
323    return new Response("Upgrade failed", { status: 500 });
324  },
325 
326  websocket: {
327    open(ws) {
328      console.log("Client connected");
329      ws.send("Welcome!");
330    },
331 
332    message(ws, message) {
333      console.log(`Received: ${message}`);
334      ws.send(`Echo: ${message}`);
335    },
336 
337    close(ws) {
338      console.log("Client disconnected");
339    },
340  },
341});
342```
343 
344### 5.4 SQLite (Bun.sql)
345 
346```typescript
347import { Database } from "bun:sqlite";
348 
349const db = new Database("mydb.sqlite");
350 
351// Create table
352db.run(`
353  CREATE TABLE IF NOT EXISTS users (
354    id INTEGER PRIMARY KEY AUTOINCREMENT,
355    name TEXT NOT NULL,
356    email TEXT UNIQUE
357  )
358`);
359 
360// Insert
361const insert = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)");
362insert.run("Alice", "alice@example.com");
363 
364// Query
365const query = db.prepare("SELECT * FROM users WHERE name = ?");
366const user = query.get("Alice");
367console.log(user); // { id: 1, name: "Alice", email: "alice@example.com" }
368 
369// Query all
370const allUsers = db.query("SELECT * FROM users").all();
371```
372 
373### 5.5 Password Hashing
374 
375```typescript
376// Hash password
377const password = "super-secret";
378const hash = await Bun.password.hash(password);
379 
380// Verify password
381const isValid = await Bun.password.verify(password, hash);
382console.log(isValid); // true
383 
384// With algorithm options
385const bcryptHash = await Bun.password.hash(password, {
386  algorithm: "bcrypt",
387  cost: 12,
388});
389```
390 
391---
392 
393## 6. Testing
394 
395### 6.1 Basic Tests
396 
397```typescript
398// math.test.ts
399import { describe, it, expect, beforeAll, afterAll } from "bun:test";
400 
401describe("Math operations", () => {
402  it("adds two numbers", () => {
403    expect(1 + 1).toBe(2);
404  });
405 
406  it("subtracts two numbers", () => {
407    expect(5 - 3).toBe(2);
408  });
409});
410```
411 
412### 6.2 Running Tests
413 
414```bash
415# Run all tests
416bun test
417 
418# Run specific file
419bun test math.test.ts
420 
421# Run matching pattern
422bun test --grep "adds"
423 
424# Watch mode
425bun test --watch
426 
427# With coverage
428bun test --coverage
429 
430# Timeout
431bun test --timeout 5000
432```
433 
434### 6.3 Matchers
435 
436```typescript
437import { expect, test } from "bun:test";
438 
439test("matchers", () => {
440  // Equality
441  expect(1).toBe(1);
442  expect({ a: 1 }).toEqual({ a: 1 });
443  expect([1, 2]).toContain(1);
444 
445  // Comparisons
446  expect(10).toBeGreaterThan(5);
447  expect(5).toBeLessThanOrEqual(5);
448 
449  // Truthiness
450  expect(true).toBeTruthy();
451  expect(null).toBeNull();
452  expect(undefined).toBeUndefined();
453 
454  // Strings
455  expect("hello").toMatch(/ell/);
456  expect("hello").toContain("ell");
457 
458  // Arrays
459  expect([1, 2, 3]).toHaveLength(3);
460 
461  // Exceptions
462  expect(() => {
463    throw new Error("fail");
464  }).toThrow("fail");
465 
466  // Async
467  await expect(Promise.resolve(1)).resolves.toBe(1);
468  await expect(Promise.reject("err")).rejects.toBe("err");
469});
470```
471 
472### 6.4 Mocking
473 
474```typescript
475import { mock, spyOn } from "bun:test";
476 
477// Mock function
478const mockFn = mock((x: number) => x * 2);
479mockFn(5);
480expect(mockFn).toHaveBeenCalled();
481expect(mockFn).toHaveBeenCalledWith(5);
482expect(mockFn.mock.results[0].value).toBe(10);
483 
484// Spy on method
485const obj = {
486  method: () => "original",
487};
488const spy = spyOn(obj, "method").mockReturnValue("mocked");
489expect(obj.method()).toBe("mocked");
490expect(spy).toHaveBeenCalled();
491```
492 
493---
494 
495## 7. Bundling
496 
497### 7.1 Basic Build
498 
499```bash
500# Bundle for production
501bun build ./src/index.ts --outdir ./dist
502 
503# With options
504bun build ./src/index.ts \
505  --outdir ./dist \
506  --target browser \
507  --minify \
508  --sourcemap
509```
510 
511### 7.2 Build API
512 
513```typescript
514const result = await Bun.build({
515  entrypoints: ["./src/index.ts"],
516  outdir: "./dist",
517  target: "browser", // or "bun", "node"
518  minify: true,
519  sourcemap: "external",
520  splitting: true,
521  format: "esm",
522 
523  // External packages (not bundled)
524  external: ["react", "react-dom"],
525 
526  // Define globals
527  define: {
528    "process.env.NODE_ENV": JSON.stringify("production"),
529  },
530 
531  // Naming
532  naming: {
533    entry: "[name].[hash].js",
534    chunk: "chunks/[name].[hash].js",
535    asset: "assets/[name].[hash][ext]",
536  },
537});
538 
539if (!result.success) {
540  console.error(result.logs);
541}
542```
543 
544### 7.3 Compile to Executable
545 
546```bash
547# Create standalone executable
548bun build ./src/cli.ts --compile --outfile myapp
549 
550# Cross-compile
551bun build ./src/cli.ts --compile --target=bun-linux-x64 --outfile myapp-linux
552bun build ./src/cli.ts --compile --target=bun-darwin-arm64 --outfile myapp-mac
553 
554# With embedded assets
555bun build ./src/cli.ts --compile --outfile myapp --embed ./assets
556```
557 
558---
559 
560## 8. Migration from Node.js
561 
562### 8.1 Compatibility
563 
564```typescript
565// Most Node.js APIs work out of the box
566import fs from "fs";
567import path from "path";
568import crypto from "crypto";
569 
570// process is global
571console.log(process.cwd());
572console.log(process.env.HOME);
573 
574// Buffer is global
575const buf = Buffer.from("hello");
576 
577// __dirname and __filename work
578console.log(__dirname);
579console.log(__filename);
580```
581 
582### 8.2 Common Migration Steps
583 
584```bash
585# 1. Install Bun
586curl -fsSL https://bun.sh/install | bash
587 
588# 2. Replace package manager
589rm -rf node_modules package-lock.json
590bun install
591 
592# 3. Update scripts in package.json
593# "start": "node index.js" → "start": "bun run index.ts"
594# "test": "jest" → "test": "bun test"
595 
596# 4. Add Bun types
597bun add -d @types/bun
598```
599 
600### 8.3 Differences from Node.js
601 
602```typescript
603// ❌ Node.js specific (may not work)
604require("module")             // Use import instead
605require.resolve("pkg")        // Use import.meta.resolve
606__non_webpack_require__       // Not supported
607 
608// ✅ Bun equivalents
609import pkg from "pkg";
610const resolved = import.meta.resolve("pkg");
611Bun.resolveSync("pkg", process.cwd());
612 
613// ❌ These globals differ
614process.hrtime()              // Use Bun.nanoseconds()
615setImmediate()                // Use queueMicrotask()
616 
617// ✅ Bun-specific features
618const file = Bun.file("./data.txt");  // Fast file API
619Bun.serve({ port: 3000, fetch: ... }); // Fast HTTP server
620Bun.password.hash(password);           // Built-in hashing
621```
622 
623---
624 
625## 9. Performance Tips
626 
627### 9.1 Use Bun-native APIs
628 
629```typescript
630// Slow (Node.js compat)
631import fs from "fs/promises";
632const content = await fs.readFile("./data.txt", "utf-8");
633 
634// Fast (Bun-native)
635const file = Bun.file("./data.txt");
636const content = await file.text();
637```
638 
639### 9.2 Use Bun.serve for HTTP
640 
641```typescript
642// Don't: Express/Fastify (overhead)
643import express from "express";
644const app = express();
645 
646// Do: Bun.serve (native, 4-10x faster)
647Bun.serve({
648  fetch(req) {
649    return new Response("Hello!");
650  },
651});
652 
653// Or use Elysia (Bun-optimized framework)
654import { Elysia } from "elysia";
655new Elysia().get("/", () => "Hello!").listen(3000);
656```
657 
658### 9.3 Bundle for Production
659 
660```bash
661# Always bundle and minify for production
662bun build ./src/index.ts --outdir ./dist --minify --target node
663 
664# Then run the bundle
665bun run ./dist/index.js
666```
667 
668---
669 
670## Quick Reference
671 
672| Task         | Command                                    |
673| :----------- | :----------------------------------------- |
674| Init project | `bun init`                                 |
675| Install deps | `bun install`                              |
676| Add package  | `bun add <pkg>`                            |
677| Run script   | `bun run <script>`                         |
678| Run file     | `bun run file.ts`                          |
679| Watch mode   | `bun --watch run file.ts`                  |
680| Run tests    | `bun test`                                 |
681| Build        | `bun build ./src/index.ts --outdir ./dist` |
682| Execute pkg  | `bunx <pkg>`                               |
683 
684---
685 
686## Resources
687 
688- [Bun Documentation](https://bun.sh/docs)
689- [Bun GitHub](https://github.com/oven-sh/bun)
690- [Elysia Framework](https://elysiajs.com/)
691- [Bun Discord](https://bun.sh/discord)
692