PaperclipOrg
Claude Agent Skill · by Sickn33

Bun Development

Install Bun Development skill for Claude Code from sickn33/antigravity-awesome-skills.

Install
Terminal · npx
$npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill bun-development
Works with Paperclip

How Bun Development fits into a Paperclip company.

Bun Development drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md701 lines
Expand
---name: bun-developmentdescription: "Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by [oven-sh/bun](https://github.com/oven-sh/bun)."risk: criticalsource: communitydate_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](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 / 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) ```typescriptconst 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 ```typescriptconst 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) ```typescriptimport { 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 ```typescriptimport { 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 ```typescriptimport { 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 ```typescriptconst 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 globals  define: {    "process.env.NODE_ENV": JSON.stringify("production"),  },   // Naming  naming: {    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 - [Bun Documentation](https://bun.sh/docs)- [Bun GitHub](https://github.com/oven-sh/bun)- [Elysia Framework](https://elysiajs.com/)- [Bun Discord](https://bun.sh/discord) ## 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.