bun

Bun Skill Reference

Product Summary

Bun is a unified JavaScript runtime, package manager, bundler, and test runner written in Zig. It replaces Node.js, npm, esbuild, and Jest with a single fast binary. Key files: bunfig.toml (configuration), bun.lock (lockfile), package.json (project metadata). Primary commands: bun run, bun install, bun build, bun test. Bun is 4x faster than Node.js on startup and 25x faster than npm for installations. Visit https://bun.com/docs for comprehensive documentation.

When to Use

Use Bun when:

• Running scripts: Execute TypeScript/JavaScript files directly without compilation steps (bun run file.ts)
• Managing dependencies: Install, add, remove, or update packages faster than npm/yarn/pnpm (bun install, bun add)
• Bundling code: Build JavaScript/TypeScript for browser or server targets with bun build
• Testing: Run Jest-compatible tests with built-in test runner (bun test)
• Building full-stack apps: Bundle server and client code together into single executables
• Monorepo workflows: Use workspaces and filtering to manage multiple packages
• Replacing Node.js: Run any Node.js-compatible code with better performance

Do not use Bun for: type checking (use tsc separately), generating type declarations, or projects requiring exact Node.js compatibility for native modules.

Quick Reference

Essential Commands

Task	Command	Notes
Run TypeScript file	bun run file.ts	Transpiles on-the-fly; omit run for short form
Run package script	bun run dev	Executes script from package.json
Install dependencies	bun install	Creates bun.lock lockfile
Add package	bun add react	Adds to dependencies; use -d for dev
Remove package	bun remove react	Removes from package.json and node_modules
Run tests	bun test	Finds *.test.ts, *.spec.ts files automatically
Build bundle	bun build ./src/index.ts --outdir ./dist	Bundles with tree-shaking, minification optional
Watch mode	bun --watch run file.ts	Re-runs on file changes
Create project	bun init	Scaffolds new project with templates

Configuration File: bunfig.toml

Located at project root or ~/.bunfig.toml (global). Optional but useful for customization.

[install]
dev = true                    # Install devDependencies
optional = true               # Install optionalDependencies
peer = true                   # Install peerDependencies
linker = "hoisted"           # "hoisted" or "isolated" (pnpm-style)
saveTextLockfile = true      # Use text bun.lock instead of binary

[serve]
port = 3000                  # Default port for Bun.serve()

[test]
root = "."                   # Test root directory
coverage = false             # Enable coverage reporting
timeout = 5000               # Per-test timeout in ms
preload = ["./setup.ts"]     # Scripts to run before tests

[run]
shell = "system"             # "system" or "bun" (Windows defaults to "bun")
bun = true                   # Auto-alias node to bun in scripts

File Types Supported

Bun natively handles: .js, .jsx, .ts, .tsx, .json, .jsonc, .toml, .yaml, .html, .css, .wasm, .node. No configuration needed—just import and use.

Key Bun APIs

API	Purpose	Example
Bun.serve()	Start HTTP server	Bun.serve({ port: 3000, fetch: handler })
Bun.file()	Read/write files	await Bun.file("path.txt").text()
Bun.write()	Write to disk	await Bun.write("out.txt", data)
Bun.build()	Bundle code	await Bun.build({ entrypoints, outdir })
Bun.Transpiler	Transpile code	new Bun.Transpiler({ loader: "tsx" })
Bun.spawn()	Run child process	Bun.spawn(["ls", "-la"])

Decision Guidance

When to Use Hoisted vs Isolated Linker

Scenario	Use	Reason
New monorepo/workspaces	isolated	Prevents phantom dependencies, stricter isolation
New single-package project	hoisted	Traditional npm behavior, simpler
Existing project (pre-v1.3.2)	hoisted	Backward compatibility
Migrating from pnpm	isolated	Matches pnpm's approach

Set in bunfig.toml: linker = "isolated" or via CLI: bun install --linker isolated

When to Use bun build vs bun run

Use Case	Tool	Why
Execute TypeScript directly	bun run	Fast transpilation, no output files
Prepare for production	bun build	Minification, tree-shaking, bundling
Ship single executable	bun build --compile	Creates standalone binary
Development server	bun run + Bun.serve()	Hot reload, fast iteration

When to Use --concurrent in Tests

Scenario	Use --concurrent	Reason
Independent async tests	Yes	Parallel execution speeds up suite
Tests with shared state	No	Use test.serial() for order-dependent tests
Database/API tests	Maybe	Only if tests don't interfere
Unit tests	Yes	Usually safe and faster

Workflow

1. Initialize a Project

bun init my-app
cd my-app

Choose template: Blank, React, or Library. Creates package.json, tsconfig.json, .gitignore.

2. Install Dependencies

bun install

Reads package.json, downloads packages, creates bun.lock. Much faster than npm.

3. Add Packages

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

Updates package.json and bun.lock automatically.

4. Write and Run Code

# Create index.ts
echo "console.log('Hello Bun!')" > index.ts

# Run it
bun run index.ts

Bun transpiles TypeScript on-the-fly; no build step needed.

5. Create HTTP Server

// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello!");
  },
});
console.log(`Listening on ${server.url}`);

bun run server.ts

6. Write Tests

// math.test.ts
import { test, expect } from "bun:test";

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

bun test

Finds and runs all *.test.ts files automatically.

7. Bundle for Production

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

Outputs optimized bundle to dist/. Use --target browser|node|bun to control output format.

8. Create Standalone Executable

bun build ./cli.ts --outfile mycli --compile
./mycli

Bundles code + Bun runtime into single executable; no dependencies needed.

Common Gotchas

• Lifecycle scripts disabled by default: Bun doesn't run postinstall scripts for security. Add trusted packages to trustedDependencies in package.json to allow them.
• bun run vs bun <script>: If a built-in Bun command exists with the same name, use bun run <script> explicitly to run package.json scripts.
• Watch mode flag placement: Use bun --watch run file.ts, not bun run file.ts --watch. Flags after the filename are passed to the script itself.
• TypeScript errors on Bun global: Install @types/bun and add "lib": ["ESNext"] to tsconfig.json compilerOptions.
• Lockfile format: Bun v1.2+ uses text bun.lock by default (not binary bun.lockb). Commit to version control.
• Auto-install disabled in CI: Set install.auto = "disable" in bunfig.toml for production to prevent unexpected package downloads.
• Node.js compatibility: Bun implements most Node.js APIs but not all. Check docs for node: module support before relying on Node-specific code.
• Bundler always bundles: Unlike esbuild, bun build always bundles by default. Use Bun.Transpiler to transpile individual files without bundling.
• No type checking in bundler: bun build does not type-check. Run tsc --noEmit separately for type validation.
• Peer dependencies installed by default: Unlike npm, Bun installs peer dependencies automatically. Set peer = false in bunfig.toml to disable.

Verification Checklist

Before submitting work with Bun:

• Run bun install to verify dependencies resolve without errors
• Run bun run <script> to test main entry point
• Run bun test and verify all tests pass
• Run bun build and check output files exist in outdir
• Verify bun.lock is committed to version control (not .gitignored)
• Check bunfig.toml for any environment-specific settings that should be removed
• Confirm no node_modules folder is committed (should be in .gitignore)
• Test with --production flag if building for deployment: bun install --production
• Verify TypeScript files have no type errors: bun run tsc --noEmit (if tsc installed)
• Check that package.json "type": "module" is set for ESM projects

Resources

Comprehensive navigation: https://bun.com/docs/llms.txt — Page-by-page listing of all Bun documentation.

Critical pages:

1. Bun Runtime — Execute files, scripts, and manage the runtime
2. Package Manager — Install, add, remove packages and manage dependencies
3. Bundler — Bundle JavaScript/TypeScript for production
4. Test Runner — Write and run Jest-compatible tests
5. bunfig.toml — Configure Bun's behavior

---

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