Skill v1.0.0

currentAutomated scan100/100

secondsky/claude-skills/bun-runtime

──Details

PublishedMay 24, 2026 at 03:41 PM

Content Hashsha256:7bbdb5037e6fa99f...

Git SHA5e92b7170451

──Files

Files (1 file, 4.1 KB)

SKILL.md4.1 KBactive

SKILL.md · 202 lines · 4.1 KB

version: "1.0.0" 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

bash

# 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:

bash

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

Important: Put Bun flags immediately after bun:

bash

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

Package.json Scripts

bash

# 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

bash

# 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:

bash

# 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:

typescript

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:

bash

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

Or in bunfig.toml:

toml

preload = ["./setup.ts"]

Use cases: polyfills, global setup, instrumentation.

Stdin Execution

bash

# Pipe code to Bun
echo "console.log('Hello')" | bun run -
 
# Redirect file
bun run - < script.js

Workspaces & Monorepos

bash

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

Debugging

bash

# 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

All versions