<< All versions
Skill v1.0.1
currentAutomated scan100/100sickn33/antigravity-awesome-skills/bun-development
2 files
──Details
PublishedMay 15, 2026 at 02:07 AM
Content Hashsha256:ca5333d326cb634e...
Git SHA82058b6f14a7
Bump Typepatch
──Files
Files (1 file, 14.2 KB)
SKILL.md14.2 KBactive
SKILL.md · 703 lines · 14.2 KB
version: "1.0.1" name: bun-development description: "Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by oven-sh/bun." risk: critical source: community date_added: "2026-02-27"
<!-- security-allowlist: curl-pipe-bash, irm-pipe-iex -->
⚡ Bun Development
Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by 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 / Linuxcurl -fsSL https://bun.sh/install | bash# Windowspowershell -c "irm bun.sh/install.ps1 | iex"# Homebrewbrew tap oven-sh/bunbrew install bun# npm (if needed)npm install -g bun# Upgradebun 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 projectbun init# Creates:# ├── package.json# ├── tsconfig.json# ├── index.ts# └── README.md# With specific templatebun create <template> <project-name># Examplesbun create react my-app # React appbun create next my-app # Next.js appbun create vite my-app # Vite appbun 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.jsonbun install # or 'bun i'# Add dependenciesbun add express # Regular dependencybun add -d typescript # Dev dependencybun add -D @types/node # Dev dependency (alias)bun add --optional pkg # Optional dependency# From specific registrybun add lodash --registry https://registry.npmmirror.com# Install specific versionbun add react@18.2.0bun add react@latestbun add react@next# From gitbun add github:user/repobun add git+https://github.com/user/repo.git
3.2 Removing & Updating
bash
# Remove packagebun remove lodash# Update packagesbun update # Update allbun update lodash # Update specificbun update --latest # Update to latest (ignore ranges)# Check outdatedbun outdated
3.3 bunx (npx equivalent)
bash
# Execute package binariesbunx prettier --write .bunx tsc --initbunx create-react-app my-app# With specific versionbunx -p typescript@4.9 tsc --version# Run without installingbunx 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 lockfilebun install --frozen-lockfile
4. Running Code
4.1 Basic Execution
bash
# Run TypeScript directly (no build step!)bun run index.ts# Run JavaScriptbun run index.js# Run with argumentsbun run server.ts --port 3000# Run package.json scriptbun run devbun run build# Short form (for scripts)bun devbun build
4.2 Watch Mode
bash
# Auto-restart on file changesbun --watch run index.ts# With hot reloadingbun --hot run server.ts
4.3 Environment Variables
typescript
// .env file is loaded automatically!// Access environment variablesconst 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 filebun --env-file=.env.production run index.ts
5. Built-in APIs
5.1 File System (Bun.file)
typescript
// Read fileconst file = Bun.file("./data.json");const text = await file.text();const json = await file.json();const buffer = await file.arrayBuffer();// File infoconsole.log(file.size); // bytesconsole.log(file.type); // MIME type// Write fileawait Bun.write("./output.txt", "Hello, Bun!");await Bun.write("./data.json", JSON.stringify({ foo: "bar" }));// Stream large filesconst 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 WebSocketif (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 tabledb.run(`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT,name TEXT NOT NULL,email TEXT UNIQUE)`);// Insertconst insert = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)");insert.run("Alice", "alice@example.com");// Queryconst 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 allconst allUsers = db.query("SELECT * FROM users").all();
5.5 Password Hashing
typescript
// Hash passwordconst password = "super-secret";const hash = await Bun.password.hash(password);// Verify passwordconst isValid = await Bun.password.verify(password, hash);console.log(isValid); // true// With algorithm optionsconst bcryptHash = await Bun.password.hash(password, {algorithm: "bcrypt",cost: 12,});
6. Testing
6.1 Basic Tests
typescript
// math.test.tsimport { 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 testsbun test# Run specific filebun test math.test.ts# Run matching patternbun test --grep "adds"# Watch modebun test --watch# With coveragebun test --coverage# Timeoutbun test --timeout 5000
6.3 Matchers
typescript
import { expect, test } from "bun:test";test("matchers", () => {// Equalityexpect(1).toBe(1);expect({ a: 1 }).toEqual({ a: 1 });expect([1, 2]).toContain(1);// Comparisonsexpect(10).toBeGreaterThan(5);expect(5).toBeLessThanOrEqual(5);// Truthinessexpect(true).toBeTruthy();expect(null).toBeNull();expect(undefined).toBeUndefined();// Stringsexpect("hello").toMatch(/ell/);expect("hello").toContain("ell");// Arraysexpect([1, 2, 3]).toHaveLength(3);// Exceptionsexpect(() => {throw new Error("fail");}).toThrow("fail");// Asyncawait 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 functionconst mockFn = mock((x: number) => x * 2);mockFn(5);expect(mockFn).toHaveBeenCalled();expect(mockFn).toHaveBeenCalledWith(5);expect(mockFn.mock.results[0].value).toBe(10);// Spy on methodconst obj = {method: () => "original",};const spy = spyOn(obj, "method").mockReturnValue("mocked");expect(obj.method()).toBe("mocked");expect(spy).toHaveBeenCalled();
7. Bundling
7.1 Basic Build
bash
# Bundle for productionbun build ./src/index.ts --outdir ./dist# With optionsbun build ./src/index.ts \--outdir ./dist \--target browser \--minify \--sourcemap
7.2 Build API
typescript
const result = await Bun.build({entrypoints: ["./src/index.ts"],outdir: "./dist",target: "browser", // or "bun", "node"minify: true,sourcemap: "external",splitting: true,format: "esm",// External packages (not bundled)external: ["react", "react-dom"],// Define globalsdefine: {"process.env.NODE_ENV": JSON.stringify("production"),},// Namingnaming: {entry: "[name].[hash].js",chunk: "chunks/[name].[hash].js",asset: "assets/[name].[hash][ext]",},});if (!result.success) {console.error(result.logs);}
7.3 Compile to Executable
bash
# Create standalone executablebun build ./src/cli.ts --compile --outfile myapp# Cross-compilebun build ./src/cli.ts --compile --target=bun-linux-x64 --outfile myapp-linuxbun build ./src/cli.ts --compile --target=bun-darwin-arm64 --outfile myapp-mac# With embedded assetsbun build ./src/cli.ts --compile --outfile myapp --embed ./assets
8. Migration from Node.js
8.1 Compatibility
typescript
// Most Node.js APIs work out of the boximport fs from "fs";import path from "path";import crypto from "crypto";// process is globalconsole.log(process.cwd());console.log(process.env.HOME);// Buffer is globalconst buf = Buffer.from("hello");// __dirname and __filename workconsole.log(__dirname);console.log(__filename);
8.2 Common Migration Steps
bash
# 1. Install Buncurl -fsSL https://bun.sh/install | bash# 2. Replace package managerrm -rf node_modules package-lock.jsonbun install# 3. Update scripts in package.json# "start": "node index.js" → "start": "bun run index.ts"# "test": "jest" → "test": "bun test"# 4. Add Bun typesbun add -d @types/bun
8.3 Differences from Node.js
typescript
// ❌ Node.js specific (may not work)require("module") // Use import insteadrequire.resolve("pkg") // Use import.meta.resolve__non_webpack_require__ // Not supported// ✅ Bun equivalentsimport pkg from "pkg";const resolved = import.meta.resolve("pkg");Bun.resolveSync("pkg", process.cwd());// ❌ These globals differprocess.hrtime() // Use Bun.nanoseconds()setImmediate() // Use queueMicrotask()// ✅ Bun-specific featuresconst file = Bun.file("./data.txt"); // Fast file APIBun.serve({ port: 3000, fetch: ... }); // Fast HTTP serverBun.password.hash(password); // Built-in hashing
9. Performance Tips
9.1 Use Bun-native APIs
typescript
// Slow (Node.js compat)import fs from "fs/promises";const content = await fs.readFile("./data.txt", "utf-8");// Fast (Bun-native)const file = Bun.file("./data.txt");const content = await file.text();
9.2 Use Bun.serve for HTTP
typescript
// Don't: Express/Fastify (overhead)import express from "express";const app = express();// Do: Bun.serve (native, 4-10x faster)Bun.serve({fetch(req) {return new Response("Hello!");},});// Or use Elysia (Bun-optimized framework)import { Elysia } from "elysia";new Elysia().get("/", () => "Hello!").listen(3000);
9.3 Bundle for Production
bash
# Always bundle and minify for productionbun build ./src/index.ts --outdir ./dist --minify --target node# Then run the bundlebun run ./dist/index.js
Quick Reference
| Task | Command | |
|---|---|---|
| Init project | bun init | |
| Install deps | bun install | |
| Add package | bun add <pkg> | |
| Run script | bun run <script> | |
| Run file | bun run file.ts | |
| Watch mode | bun --watch run file.ts | |
| Run tests | bun test | |
| Build | bun build ./src/index.ts --outdir ./dist | |
| Execute pkg | bunx <pkg> |
Resources
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.