Bun Skill Reference

Product Summary

Bun is an all-in-one JavaScript/TypeScript runtime and toolkit. It replaces Node.js, npm, Jest, and esbuild with a single fast executable. Bun runs TypeScript and JSX natively without configuration, starts 4x faster than Node.js, and includes a package manager (30x faster than npm), test runner (Jest-compatible), and bundler.

Key files and commands:

• bunfig.toml — Bun configuration (optional, in project root)
• package.json — Standard Node.js manifest; Bun reads it directly
• bun run <file> — Execute TypeScript/JavaScript files
• bun install — Install dependencies (creates bun.lock)
• bun test — Run tests (finds *.test.ts, *.spec.ts, etc.)
• bun build — Bundle code for production
• bunx <package> — Execute packages without installing

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

---

When to Use

Use this skill when:

• Running TypeScript or JSX files directly without compilation
• Installing or managing npm packages faster than npm/yarn/pnpm
• Writing and running tests with a Jest-like API
• Bundling JavaScript/TypeScript for browsers or servers
• Building full-stack applications with HTML imports
• Executing package.json scripts with bun run
• Setting up a new project with bun init
• Deploying to production with bun build

Do not use for:

• Type checking (use tsc separately)
• Generating TypeScript type declarations
• Projects that require Node.js-specific APIs not yet in Bun (check compatibility)

---

Quick Reference

Essential Commands

Task	Command
Run a file	bun run index.ts or bun index.ts
Run a script	bun run dev (from package.json scripts)
Install deps	bun install
Add a package	bun add react
Add dev dep	bun add -d @types/react
Remove package	bun remove react
Run tests	bun test
Watch tests	bun test --watch
Bundle code	bun build ./index.ts --outdir ./dist
Watch bundler	bun build ./index.ts --outdir ./dist --watch
Execute package	bunx cowsay "Hello"
Initialize project	bun init

File Conventions

Pattern	Meaning
*.test.ts, *.test.js	Test files (auto-discovered)
*_test.ts, *_spec.ts	Alternative test patterns
bunfig.toml	Bun configuration (optional)
bun.lock	Lockfile (text format, commit to git)
.env	Environment variables (auto-loaded)

Configuration in bunfig.toml

# Runtime
[serve]
port = 3000

[test]
root = "./__tests__"
coverage = true
timeout = 5000

[install]
optional = true
dev = true
production = false
linker = "hoisted"  # or "isolated"

[run]
shell = "system"
bun = true
silent = false

---

Decision Guidance

When to use bun run vs bun <file>

Scenario	Use
Running a script from package.json	bun run dev
Running a file directly	bun index.ts or bun run index.ts
Running with Bun flags (watch, etc.)	bun --watch run index.ts
Running a system command	bun run ls (inside package.json script)

When to use bun install vs bun add

Scenario	Use
Install all dependencies from package.json	bun install
Add a new package	bun add react
Add a dev dependency	bun add -d typescript
Install in production (no devDeps)	bun install --production
Frozen lockfile (CI/CD)	bun install --frozen-lockfile

When to use hoisted vs isolated linker

Scenario	Use
Traditional npm behavior, shared node_modules	hoisted
Strict dependency isolation, prevent phantom deps	isolated
New workspaces/monorepos	isolated (default)
Existing projects	hoisted (default for backward compat)

When to bundle vs run directly

Scenario	Use
Development, rapid iteration	bun run (no bundling)
Production server code	bun build --target bun
Browser/client code	bun build --target browser
Node.js compatibility	bun build --target node
Single executable	bun build --target bun --outfile app

---

Workflow

1. Start a New Project

bun init
# Choose template: Blank, React, or Library
cd my-app
bun run index.ts

2. Add Dependencies

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

3. Write and Run Code

# Edit index.ts with TypeScript/JSX
bun run index.ts

# Or watch for changes
bun --watch run index.ts

4. Write Tests

Create math.test.ts:

import { test, expect } from "bun:test";

test("2 + 2 = 4", () => {
  expect(2 + 2).toBe(4);
});

Run tests:

bun test
bun test --watch
bun test --coverage

5. Build for Production

# Bundle for browser
bun build ./src/index.tsx --outdir ./dist --target browser

# Bundle for server
bun build ./src/server.ts --outdir ./dist --target bun

# Create single executable
bun build ./src/server.ts --outfile app --target bun

6. Configure bunfig.toml (Optional)

[serve]
port = 8080

[test]
coverage = true
timeout = 10000

[install]
linker = "isolated"

7. Deploy

# Build for production
bun build ./src/server.ts --outdir ./dist --minify

# Run in production
bun ./dist/server.js

---

Common Gotchas

• TypeScript errors on Bun global: Install @types/bun and configure tsconfig.json with "lib": ["ESNext"]
• Lifecycle scripts don't run by default: Add packages to trustedDependencies in package.json to allow postinstall scripts
• bun run flags must come before the script name: Use bun --watch run dev, not bun run dev --watch
• Test files must match patterns: Use *.test.ts, *_test.ts, *.spec.ts, or *_spec.ts
• Environment variables auto-load from .env: Disable with env = false in bunfig.toml if needed
• bun.lock is text format: Commit it to git; it's human-readable and mergeable
• Peer dependencies install by default: Unlike npm, Bun installs peerDependencies automatically
• Node.js compatibility is ongoing: Check Node.js compat docs for unsupported APIs
• Bundler doesn't type-check: Run tsc --noEmit separately for type checking
• Auto-install disabled in production: Set install.auto = "disable" in bunfig.toml for CI/CD

---

Verification Checklist

Before submitting work with Bun:

• Tests pass: bun test runs without errors
• No TypeScript errors: bunx tsc --noEmit (if using TypeScript)
• Code runs locally: bun run index.ts or bun run dev
• Dependencies are declared: bun add <package> (not manually edited package.json)
• bun.lock is committed (if using version control)
• bunfig.toml is configured for your use case (if needed)
• Build succeeds: bun build ./src/index.ts --outdir ./dist
• No console errors or warnings in output
• Environment variables are set (check .env or CI/CD config)
• Trusted dependencies are declared if using lifecycle scripts

---

Resources

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

Critical documentation pages:

1. Bun Runtime — Execute files and scripts
2. Package Manager — Install and manage dependencies
3. Test Runner — Write and run tests
4. Bundler — Bundle code for production
5. HTTP Server — Build servers with Bun.serve

---

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