Bun Development
When to Use This Skill
| Scenario | Use this skill | Alternative |
|---|---|---|
| Running scripts with Bun runtime | Yes | nodejs-development for Node.js-specific runtime |
Running Bun tests with bun test | Yes | bun-test for quick invocable test runs |
| Bundling/building with Bun | Yes | bun-build for quick invocable builds |
| Initializing a new Bun project | Yes | nodejs-development for Vite/Vue scaffolding |
| Compiling to standalone executable | Yes | N/A |
| Installing or managing dependencies | No - use bun-package-manager | bun-add for quick package additions |
| Publishing packages to npm | No - use bun-publishing | N/A |
| Debugging TypeScript/JS code | No - use typescript-debugging | N/A |
Core Expertise
Bun is an all-in-one JavaScript runtime:
- ~6ms startup vs npm's ~170ms
- Native TypeScript execution
- Built-in test runner
- Fast bundler with compile-to-exe
Running Scripts
Basic Execution
# Run package.json script
bun run <script>
# Run file directly
bun <file.ts>
# Silent mode (no script echo)
bun run --silent <script>
Watch Mode
# Auto-restart on changes
bun --watch run dev
# Hot reload (preserve state)
bun --hot run dev
Workspace Scripts
# Run in matching workspaces
bun run --filter 'package-*' build
# Run in all workspaces
bun run --workspaces test
# Limit output per workspace
bun run --filter '*' --elide-lines=5 build
Execute Packages (bunx)
# Execute package binary (like npx)
bunx <package>
# Specific version
bunx typescript@5.0 --help
# When binary differs from package
bunx -p @angular/cli ng new app
# Force Bun runtime
bunx --bun vite dev
Testing
Basic Test Execution
# Run all tests
bun test
# Run specific file
bun test tests/auth.test.ts
# Filter by name
bun test -t "login"
Compact Output (Agentic)
# Minimal dots reporter
bun test --dots
# Fail fast
bun test --bail
bun test --bail=3 # Stop after 3 failures
# Combine for quick feedback
bun test --dots --bail=1
CI/CD Output
# JUnit XML (most CI systems)
bun test --reporter=junit --reporter-outfile=junit.xml
# GitHub Actions (auto-detected in CI)
# Produces annotations automatically
bun test
Coverage
# Enable coverage
bun test --coverage
# LCOV format for tools
bun test --coverage --coverage-reporter=lcov
Test Configuration
# Custom timeout
bun test --timeout=10000
# Run concurrently
bun test --concurrent
# Limit concurrency
bun test --max-concurrency=5
# Detect flaky tests
bun test --rerun-each=3
Building
Bundle JavaScript/TypeScript
# Basic bundle
bun build ./src/index.ts --outdir=dist
# Production build
bun build ./src/index.ts --outdir=dist --minify --sourcemap=external
# Watch mode
bun build ./src/index.ts --outdir=dist --watch
Build Targets
# Browser (default)
bun build ./src/index.ts --target=browser
# Bun runtime
bun build ./src/index.ts --target=bun
# Node.js
bun build ./src/index.ts --target=node
Compile to Executable
# Standalone binary
bun build --compile ./app.ts --outfile myapp
# Minified standalone
bun build --compile --minify ./app.ts --outfile myapp
# Cross-compile
bun build --compile --target=bun-linux-x64 ./app.ts
Code Splitting
# Enable splitting
bun build ./src/index.ts --outdir=dist --splitting
Project Initialization
Quick Init
# Interactive blank project
bun init
# With template
bun init --react my-app
bun init --react=tailwind my-app
Create from Template
# From npm/GitHub
bun create vite my-project
bun create hono@latest my-api
# From GitHub repo
bun create <user>/<repo> destination
Agentic Optimizations
| Context | Command |
|---|---|
| Quick test | bun test --dots --bail=1 |
| CI test | bun test --reporter=junit --reporter-outfile=junit.xml |
| Coverage | bun test --coverage --coverage-reporter=lcov |
| Silent run | bun run --silent <script> |
| Watch dev | bun --watch run dev |
| Prod build | bun build --minify --sourcemap=external --outdir=dist |
| Compile | bun build --compile --minify ./app.ts |
| Memory save | bun run --smol <script> |
Quick Reference
bun run
| Flag | Description |
|---|---|
--watch | Auto-restart on changes |
--hot | Hot reload |
--silent | Suppress script echo |
--filter | Run in matching workspaces |
--smol | Reduce memory usage |
bun test
| Flag | Description |
|---|---|
--dots | Compact dot reporter |
--bail / --bail=N | Stop after N failures |
--coverage | Enable coverage |
--timeout=<ms> | Per-test timeout |
--reporter=junit | JUnit XML output |
-t <pattern> | Filter by test name |
--concurrent | Parallel async tests |
bun build
| Flag | Description |
|---|---|
--outdir | Output directory |
--outfile | Output file (single/compile) |
--minify | Minify output |
--sourcemap | none/inline/external |
--target | browser/bun/node |
--compile | Standalone executable |
--splitting | Enable code splitting |
--watch | Watch mode |
Environment Variables
| Variable | Description |
|---|---|
BUN_OPTIONS | Global CLI flags |
NODE_ENV | Environment (production/development) |