/bun-runtime

name: bun-runtime
description: Use for Bun runtime, bunfig.toml, watch/hot modes, env vars, CLI flags, and module resolution.
metadata:
  version: "1.0.0"
license: MIT

Bun Runtime

Bun is a fast all-in-one JavaScript runtime built on JavaScriptCore (Safari's engine). It provides 4x faster startup than Node.js on Linux.

Quick Start

# Run a file
bun run index.ts
bun index.ts  # shorthand

# Run with watch mode
bun --watch run index.ts

# Run package.json script
bun run dev

# Run with hot reloading
bun --hot run server.ts

Core CLI Flags

| Flag | Purpose | |------|---------| | `--watch` | Restart on file changes | | `--hot` | Hot module replacement (preserves state) | | `--smol` | Reduce memory usage (slower GC) | | `--inspect` | Enable debugger | | `--preload` | Load modules before execution | | `--env-file` | Load specific .env file | | `-e, --eval` | Evaluate code string |

Running Files

Bun transpiles TypeScript and JSX on-the-fly:

bun run index.js
bun run index.ts
bun run index.jsx
bun run index.tsx

**Important**: Put Bun flags immediately after `bun`:

bun --watch run dev    # Correct
bun run dev --watch    # Wrong - flag passed to script

Package.json Scripts

# Run script
bun run dev
bun dev  # shorthand (if no Bun command conflicts)

# List available scripts
bun run

# Run with Bun instead of Node
bun run --bun vite

Bun respects lifecycle hooks (`preclean`, `postclean`, etc.).

Watch Mode vs Hot Reloading

| Mode | Flag | Behavior | |------|------|----------| | Watch | `--watch` | Full process restart on changes | | Hot | `--hot` | Replace modules, preserve state |

# Watch mode - full restart
bun --watch run server.ts

# Hot reloading - preserves connections/state
bun --hot run server.ts

Environment Variables

Bun automatically loads `.env` files:

# Loads automatically: .env, .env.local, .env.development
bun run index.ts

# Specify env file
bun --env-file .env.production run index.ts

# Disable auto-loading
# In bunfig.toml: env = false

Access in code:

const apiKey = process.env.API_KEY;
const bunEnv = Bun.env.NODE_ENV;

Globals Available

| Global | Source | Notes | |--------|--------|-------| | `Bun` | Bun | Main API object | | `Buffer` | Node.js | Binary data | | `process` | Node.js | Process info | | `fetch` | Web | HTTP requests | | `Request/Response` | Web | HTTP types | | `WebSocket` | Web | WebSocket client | | `crypto` | Web | Cryptography | | `console` | Web | Logging | | `__dirname` | Node.js | Current directory | | `__filename` | Node.js | Current file |

Preload Scripts

Load modules before your main script:

bun --preload ./setup.ts run index.ts

Or in `bunfig.toml`:

preload = ["./setup.ts"]

Use cases: polyfills, global setup, instrumentation.

Stdin Execution

# Pipe code to Bun
echo "console.log('Hello')" | bun run -

# Redirect file
bun run - < script.js

Workspaces & Monorepos

# Run script in specific packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

Debugging

# Start debugger
bun --inspect run index.ts

# Wait for debugger connection
bun --inspect-wait run index.ts

# Break on first line
bun --inspect-brk run index.ts

Connect via Chrome DevTools or VS Code.

Common Errors

| Error | Cause | Fix | |-------|-------|-----| | `Cannot find module` | Missing dependency | Run `bun install` | | `Top-level await` | Using await outside async | Wrap in async function or use `.mts` | | `--watch not working` | Flag in wrong position | Put flag before `run` |

When to Load References

Load `references/bunfig.md` when:

• Configuring bunfig.toml
• Setting up test configuration
• Configuring package manager behavior
• Setting JSX options

Load `references/cli-flags.md` when:

• Need complete CLI flag reference
• Configuring advanced runtime options
• Setting up debugging

Load `references/module-resolution.md` when:

• Troubleshooting import errors
• Configuring path aliases
• Understanding Bun's resolution algorithm