Bun Cheatsheet

Quick Start

``bash # Run a script bun run index.ts

# Watch mode — auto-restart on changes bun run --watch index.ts

# Dev mode with hot reload bun --hot server.ts

# Start dev server (from package.json scripts) bun dev

# Install dependencies bun install

# Add a package bun add zod

# Run a one-off npm package bun x cowsay 'hello bun'

# Run tests bun test `

Install & Setup

`bash bun --version # Show version bun upgrade # Upgrade to latest bun --help # Show help `

Basic Usage

`bash bun run index.ts # Run a file bun run --watch index.ts # Watch mode (auto-restart) bun --hot server.ts # Hot reload (no restart needed) bun --smol index.ts # Low memory mode bun . # Auto-detect entry point bun dev # Run dev script from package.json bun start # Run start script from package.json `

Package Management

`bash bun install # Install all dependencies bun add zod # Add a dependency bun add -d @types/bun # Add a dev dependency bun add --exact zod@3.23.0 # Add with exact version bun remove zod # Remove a dependency bun update # Update all dependencies bun pm cache # View/clear package cache bun pm ls # List installed dependencies `

Testing & Debug

`bash bun test # Run all tests bun test --watch # Watch mode bun test --coverage # With coverage report bun test --bail # Stop on first failure bun test --timeout 10000 # Per-test timeout (ms) `

Bundler

`bash bun build ./src/index.ts --outdir ./dist # Bundle to single file bun build --target bun ./src/index.ts --outdir ./dist # Target Bun runtime bun build --minify ./src/index.ts --outdir ./dist # Minify output bun build --splitting ./src/pages/*.tsx --outdir ./dist # Code splitting bun build --sourcemap=external ./src/index.ts --outdir ./dist # External source maps `

Advanced

`bash bun x cowsay 'hello' # Run npm package without installing bun create next-app # Create project from template bun init # Initialize new project bun link # Register local package globally bun patch lodash # Patch an installed npm package bun publish # Publish to npm registry bun fig # Generate Fig autocomplete spec `

FAQ

### How do I configure Bun?

Create a bunfig.toml in your project root (~/.bunfig.toml also works). Example:

`toml [install] cache = true production = false frozenLockfile = false registry = "https://registry.npmjs.org/"

[test] preload = "./test/setup.ts" `

### How does bun.lock work?

Bun uses a binary lockfile format (bun.lock) instead of JSON. It's faster to parse and smaller on disk. You can convert to/from package-lock.json with plugins. Commit it to version control. To regenerate: delete both node_modules and bun.lock, then run bun install.

### How do I use Env variables with Bun?

Bun automatically loads .env files — no need for dotenv. It reads .env, .env.local, .env.production (based on NODE_ENV). Access via process.env:

`typescript const db = process.env.DATABASE_URL; `

### Can I use Bun with existing Node.js projects?

Yes! Run bun install in any Node.js project to replace npm/yarn. For most projects, bun run dev / bun run build` works since Bun runs package.json scripts and is compatible with the Node.js API. Some projects may need minor adjustments for edge-case Node.js internals.