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

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

Decision Guidance

When to Use Hoisted vs Isolated Linker

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

When to Use bun build vs bun run

When to Use --concurrent in Tests

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