Bun Skill

Product summary

Bun is an all-in-one JavaScript/TypeScript toolkit that ships as a single executable. It includes a runtime (drop-in Node.js replacement), package manager (faster than npm), bundler (faster than esbuild), and test runner (Jest-compatible). The runtime uses JavaScriptCore and is written in Zig, delivering 4x faster startup than Node.js.

Key files and commands:

bunfig.toml — Configuration file (optional, zero-config by default)
bun run <file> — Execute JavaScript/TypeScript files with native transpilation
bun install — Install dependencies 25x faster than npm
bun build <entry> — Bundle for browser or server
bun test — Run Jest-compatible tests
package.json — Standard Node.js package manifest (fully compatible)

Primary docs: https://bun.com/docs

---

When to use

Reach for this skill when:

Running scripts or servers — bun run is 28x faster than npm run; use for any TypeScript/JSX execution
Installing dependencies — bun install is 25x faster; works in existing Node.js projects
Bundling for production — bun build bundles JS/TS/JSX/CSS for browsers or servers; 1.75x faster than esbuild
Testing — bun test runs Jest-compatible tests with TypeScript support, snapshots, mocking, and watch mode
Building full-stack apps — HTML imports + Bun.serve enable bundling frontend and backend in one command
Migrating from Node.js — Bun is a drop-in replacement; most Node.js code works without changes
Optimizing startup time — Bun's transpiler and runtime eliminate overhead; ideal for CLI tools and serverless functions

---

Quick reference

Essential commands

Command	Purpose
`bun run <file>`	Execute JS/TS/JSX/TSX file
`bun run <script>`	Run package.json script
`bun install`	Install all dependencies
`bun add <pkg>`	Add a package
`bun remove <pkg>`	Remove a package
`bun build <entry> --outdir ./out`	Bundle for production
`bun test`	Run all tests
`bun init`	Create new Bun project

File conventions

Pattern	Behavior
`.test.ts`, `.test.js`	Test files (auto-discovered)
`_test.ts`, `.spec.ts`	Alternative test patterns
`bunfig.toml`	Configuration (optional)
`bun.lock`	Lockfile (text format, commit to version control)
`.env`	Environment variables (auto-loaded)

Configuration in bunfig.toml

# Runtime
[run]
shell = "bun"  # or "system"
bun = true     # alias node to bun in scripts

# Package manager
[install]
linker = "hoisted"  # or "isolated" for monorepos
dev = true
optional = true
production = false

# Test runner
[test]
root = "."
coverage = false
timeout = 5000

# Server
[serve]
port = 3000

Common procedures

Initialize a project:

bun init my-app
cd my-app
bun run index.ts

Add a dependency:

bun add react
bun add -d typescript  # dev dependency

Run a script from package.json:

bun run dev
bun run build

Bundle for production:

bun build ./src/index.tsx --outdir ./dist --minify

Run tests with coverage:

bun test --coverage

Create an HTTP server:

const server = Bun.serve({
  port: 3000,
  routes: {
    "/": () => new Response("Hello"),
    "/api/users/:id": (req) => new Response(`User ${req.params.id}`),
  },
});
console.log(`Server at ${server.url}`);

---

Decision guidance

When to use `bun run` vs `bun build`

Use `bun run`	Use `bun build`
Development, scripts, one-off execution	Production bundles, browser code, optimization
Direct file execution with transpilation	Minification, tree-shaking, code splitting
Testing, debugging, local development	Deployment, distribution, performance-critical

When to use `hoisted` vs `isolated` linker

Hoisted	Isolated
Traditional npm behavior, flat node_modules	Strict dependency isolation, prevents phantom deps
Single-package projects (default)	Monorepos, workspaces (default)
Faster installs, simpler resolution	Stricter, more predictable, pnpm-like

When to use `Bun.serve` vs framework

Bun.serve	Framework (Express, Elysia, Hono)
Simple APIs, minimal dependencies	Complex routing, middleware, plugins
Maximum performance, zero overhead	Developer experience, ecosystem
Built-in routing, WebSocket, streaming	Type safety, validation, decorators

When to use `bun test` vs external test runner

bun test	Jest/Vitest
TypeScript out of box, no config	Mature ecosystem, more plugins
Fast, Jest-compatible API	Better IDE integration in some cases
Built-in mocking, snapshots, watch	More customization options

---

Workflow

Typical task: Build and deploy a full-stack app

Initialize project

   bun init my-app
   cd my-app

Create server code (server.ts)

   import index from "./index.html";
   
   Bun.serve({
     routes: {
       "/": index,
       "/api/data": () => Response.json({ data: [] }),
     },
   });

Create frontend (index.html with React/TypeScript)

   <!DOCTYPE html>
   <html>
     <head><title>App</title></head>
     <body>
       <div id="root"></div>
       <script type="module" src="./client.tsx"></script>
     </body>
   </html>

Install dependencies

   bun add react react-dom
   bun add -d @types/bun

Test locally

   bun run server.ts
   # Visit http://localhost:3000

Build for production

   bun build ./server.ts --target bun --outfile ./dist/server

Deploy (e.g., to Vercel, Railway, or Docker)

   # Dockerfile
   FROM oven/bun
   COPY . /app
   WORKDIR /app
   RUN bun install
   CMD ["bun", "run", "server.ts"]

Typical task: Add tests to existing project

Create test file (math.test.ts)

   import { test, expect } from "bun:test";
   
   test("addition", () => {
     expect(2 + 2).toBe(4);
   });

Run tests

   bun test

Add coverage

   bun test --coverage

Watch mode

   bun test --watch

Typical task: Migrate from npm to Bun

Check compatibility — Most Node.js projects work as-is
Replace npm with bun

   rm -rf node_modules package-lock.json
   bun install  # Creates bun.lock

Update CI/CD — Replace npm install with bun install, npm run with bun run
Test thoroughly — Run your test suite with bun test
Commit lockfile — bun.lock should be committed to version control

---

Common gotchas

TypeScript errors on Bun global — Install @types/bun and configure tsconfig.json with "lib": ["ESNext"]
Lifecycle scripts disabled by default — Add trusted packages to trustedDependencies in package.json to allow postinstall scripts
Auto-install can mask missing dependencies — Use --frozen-lockfile in CI to catch mismatches
Bundler always bundles — Use Bun.Transpiler if you need per-file transpilation without bundling
bun run flags must come after bun, not after script name — bun --watch run dev ✓, bun run dev --watch ✗
Environment variables not inlined by default — Use env: "inline" in bun build or --env inline CLI flag
Monorepo linker defaults differ — New workspaces use isolated, existing projects use hoisted; explicitly set in bunfig.toml to avoid surprises
Node.js compatibility is ongoing — Check /runtime/nodejs-compat for unsupported APIs; some Node.js modules may not work
Bun.serve routes are static — Use fetch() handler for dynamic routing; routes object is for static paths and parameters
Test discovery is automatic — No need to specify test files; bun test finds all *.test.ts files recursively

---

Verification checklist

Before submitting work with Bun:

[ ] Dependencies installed — Run bun install and verify bun.lock is created
[ ] Code runs locally — bun run <entry> executes without errors
[ ] Tests pass — bun test shows all tests passing
[ ] TypeScript compiles — No type errors in editor or from bun check (if available)
[ ] Bundler output valid — bun build completes without errors; output files exist
[ ] Environment variables set — .env file exists or CI/CD has required vars
[ ] Lockfile committed — bun.lock is in version control (not .gitignored)
[ ] No Node.js-specific APIs — If targeting Bun, avoid unsupported Node.js modules
[ ] Trusted dependencies declared — If using postinstall scripts, add to trustedDependencies
[ ] Performance verified — For production, confirm bundle size and startup time are acceptable

---

Resources

Comprehensive navigation: https://bun.com/docs/llms.txt

Critical pages:

Runtime overview — Execute files, run scripts, environment
Package manager — Install, add, remove, workspaces
Bundler — Build for browser and server, code splitting, plugins
Test runner — Write tests, mocking, snapshots, coverage
HTTP server — Bun.serve, routing, WebSocket, TLS

---

For additional documentation and navigation, see: https://bun.com/docs/llms.txt

bun

Bun Skill

Product summary

When to use

Quick reference

Essential commands

File conventions

Configuration in bunfig.toml

Common procedures

Decision guidance

When to use `bun run` vs `bun build`

When to use `hoisted` vs `isolated` linker

When to use `Bun.serve` vs framework

When to use `bun test` vs external test runner

Workflow

Typical task: Build and deploy a full-stack app

Typical task: Add tests to existing project

Typical task: Migrate from npm to Bun

Common gotchas

Verification checklist

Resources

Score

Bun FAQ

How do I install the Bun skill?

What does the Bun skill do?

Is the Bun skill free?

Does Bun work with Claude Code and OpenClaw?

Recommended skills

Related guides

bun

Bun Skill

Product summary

When to use

Quick reference

Essential commands

File conventions

Configuration in bunfig.toml

Common procedures

Decision guidance

When to use bun run vs bun build

When to use hoisted vs isolated linker

When to use Bun.serve vs framework

When to use bun test vs external test runner

Workflow

Typical task: Build and deploy a full-stack app

Typical task: Add tests to existing project

Typical task: Migrate from npm to Bun

Common gotchas

Verification checklist

Resources

Score

Bun FAQ

How do I install the Bun skill?

What does the Bun skill do?

Is the Bun skill free?

Does Bun work with Claude Code and OpenClaw?

Recommended skills

Related guides

When to use `bun run` vs `bun build`

When to use `hoisted` vs `isolated` linker

When to use `Bun.serve` vs framework

When to use `bun test` vs external test runner