OpenSkillIndex← back to search
claude-code

Learn-skills.dev bun-expert

install
source · Clone the upstream repo
git clone https://github.com/NeverSight/learn-skills.dev
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/abpai/skills/bun-expert" ~/.claude/skills/neversight-learn-skills-dev-bun-expert && rm -rf "$T"
manifest: data/skills-md/abpai/skills/bun-expert/SKILL.md
source content

Bun Runtime Development Guide

This skill is intentionally grounded in official Bun documentation. Bun moves quickly, so prefer current docs over hard-coded release timelines or benchmark claims.

Project Setup

Initialize a new project

bun init                      # Interactive setup (package.json + tsconfig.json)
bun init -y                   # Accept defaults
bun create <template> <dir>   # Scaffold from a template

TypeScript notes

  • Bun runs TypeScript directly.
  • bun init
    generates a compatible 
    tsconfig.json
    .
  • Add extra typing packages only when your editor/toolchain requires them.

Package Management

Essential commands

bun install
bun add <pkg>
bun add -d <pkg>
bun add -g <pkg>
bun remove <pkg>
bun update
bunx <pkg>

Lockfile

  • bun.lock
    is the default text lockfile format in modern Bun.
  • bun.lockb
    remains supported for compatibility.
  • Force text lockfile output:
bun install --save-text-lockfile

Diagnostics and security

bun why <pkg>
bun audit
bun list
bun pm migrate

Monorepo catalogs

Bun supports dependency catalogs in workspace roots:

{
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "typescript": "^5.7.0"
    }
  }
}

Reference from packages:

{
  "dependencies": {
    "react": "catalog:"
  }
}

Running Code

bun index.ts
bun run start
bun --watch index.ts
bun --hot index.ts

Environment variables

Bun auto-loads 

.env
files. Order is:

  1. .env
  2. .env.{NODE_ENV}
    (
    development
    , 
    production
    , 
    test
    )
  3. .env.local
const apiKey = process.env.API_KEY;
const bunApiKey = Bun.env.API_KEY;

HTML entrypoints (zero-config)

bun --hot index.html
bun --watch index.html

HTTP Server

Bun supports route-based servers with 

Bun.serve()
.

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

Built-in API Map

NeedBun API
HTTP server + WebSockets
Bun.serve()
SQL databases
sql
, 
SQL
, 
Bun.sql
, 
Bun.SQL
S3-compatible storage
s3
, 
S3Client
Redis
redis
, 
RedisClient
Shell scripting
Bun.$
/ 
$
Local files
Bun.file
, 
Bun.write
SQLite (embedded)
bun:sqlite
Password hashing
Bun.password

Testing and Bundling

Test runner (
bun test
)

bun test
bun test --watch
bun test --test-name-pattern "auth"
bun test --bail
bun test --coverage
bun test --coverage-reporter text

Bundling

bun build ./src/index.ts --outdir ./dist
bun build --target=bun ./src/server.ts --outfile ./dist/server.js
bun build --compile ./src/cli.ts --outfile ./dist/my-cli

Node.js Migration Checklist

  1. Install Bun and run 
    bun install
    .
  2. Keep existing Node APIs where they work; Bun is highly Node-compatible.
  3. Replace tooling incrementally (
    bun test
    , 
    bun build
    , 
    bun run
    ).
  4. Adopt Bun-native APIs where they simplify code (
    Bun.serve
    , 
    sql
    , 
    redis
    , 
    s3
    , 
    Bun.$
    ).
  5. Run your full tests in CI on Bun before removing Node-specific fallbacks.

Deep-Dive References

ReferenceContents
references/builtin-apis.md
Bun.serve
, SQL, S3, Redis, shell, filesystem, crypto/password utilities
references/testing-and-bundling.md
bun test
usage, mocking patterns, 
bun build
CLI and API
references/node-migration.mdPractical Node-to-Bun migration steps and compatibility guidance

Authoritative Docs