secondsky/claude-skills / plugins/bun/skills/bun-runtime
bun-runtime
VerifiedUse for Bun runtime, bunfig.toml, watch/hot modes, env vars, CLI flags, and module resolution.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |