name	bun-runtime
description	Master Bun runtime workflows for full-stack development. Monorepos, bunx, lockfiles, performance optimization, and integration patterns.
triggers	bun runtime, bunx, monorepo, bun workflows, bun performance, fast startup

Bun Runtime Workflows

Leverage Bun's integrated toolkit for faster development. From one-off commands with bunx to optimizing monorepos, master the workflows that keep full-stack teams moving.

Why Bun?

Bun is a complete toolkit in a single binary:

Runtime — JavaScript/TypeScript execution (4x faster Node startup)
Package Manager — Replaces npm/yarn (faster installs)
Bundler — Built-in code bundling
Test Runner — Native test framework (no external runners)

All in one. No configuration. No separate tools.

1. bunx: No Global Installs

Replace globally installed CLI tools with bunx. Each command runs the latest version without cluttering your environment.

Pattern: Use bunx Instead of Global npm

# ❌ Old way (npm)
npm install -g eslint
npx eslint .

# ✅ New way (Bun)
bunx eslint .
bunx eslint --fix .

# Always uses latest version, no global pollution

Common bunx Commands

# Create projects
bunx create-vite@latest my-app --template react-ts
bunx create-next-app@latest my-blog

# Run tools
bunx eslint . --fix
bunx prettier . --write
bunx tsc --noEmit

# Utilities
bunx tsx script.ts          # Run TypeScript directly
bunx esbuild app.ts         # Bundle app
bunx http-server .          # Quick HTTP server

Why bunx?

No global cluttering — Each tool installs to temp directory
Version consistency — Everyone uses the latest (or pinned) version
Faster — No global npm cache to manage
Reproducible — Same versions across developers and CI

2. Bun Workspaces: Monorepo Management

Define workspaces in root package.json for seamless monorepo management.

Setup

{
  "name": "my-workspace",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*",
    "plugins/*"
  ]
}

Directory Structure

my-workspace/
├── package.json              # Root (defines workspaces)
├── packages/
│   ├── core/                # Shared library
│   │   ├── package.json
│   │   └── src/
│   └── utils/
│       ├── package.json
│       └── src/
├── apps/
│   ├── web/                 # Next.js app
│   │   ├── package.json
│   │   └── src/
│   └── mobile/              # React Native
│       ├── package.json
│       └── src/
└── plugins/                 # Claude Code plugins
    ├── my-plugin/
    │   ├── package.json
    │   └── src/

Cross-Workspace Dependencies

Use workspace:* protocol for local dependencies:

{
  "name": "@myapp/web",
  "dependencies": {
    "@myapp/core": "workspace:*",
    "@myapp/utils": "workspace:*"
  }
}

Benefits:

Automatic linking (no npm install needed)
Changes to packages/* update immediately
Single bun install in root
No node_modules duplication

Workspace Commands

# Install all dependencies
bun install

# Run script in specific workspace
bun --filter web run dev

# Run test in all workspaces with changes
bun test --recursive

# List workspaces
bun workspaces list

3. Lockfile Management: Reproducibility

Bun creates a binary lockfile (bun.lockb) for fast, reliable builds.

Key Practices

# Generate lockfile
bun install

# Commit bun.lockb to git
git add bun.lockb
git commit -m "chore: update dependencies"

# CI: Install with frozen lockfile
bun install --frozen-lockfile

# Production: Skip dev dependencies
bun install --production

Why bun.lockb?

Fast to parse — Binary format (faster than JSON)
Reliable — Exact versions always reproduced
Smaller — More compact than package-lock.json
Deterministic — Same install on every machine

Dependency Pinning

{
  "dependencies": {
    "react": "^18.2.0",      // Patch updates ok
    "typescript": "5.7.2"    // Exact version (no updates)
  }
}

4. Bun Built-In Tools: Bundling & Testing

Bundling with Bun

# Bundle with default settings
bun build ./src/index.ts --outdir=./dist

# Minify and split chunks
bun build ./src/index.ts --minify --splitting

# Watch mode
bun build ./src/index.ts --watch

Testing with Bun's Test Runner

# Run all tests
bun test

# Run specific test file
bun test src/math.test.ts

# Watch mode (rerun on changes)
bun test --watch

# Coverage
bun test --coverage

No separate test runner needed. It's built in.

5. Performance Optimization

Startup Time

Bun has 4x faster startup than Node:

# Node.js
time node script.js
# real    0m0.345s

# Bun
time bun script.ts
# real    0m0.085s

Why?

Written in Rust (not C++)
JavaScriptCore engine (Apple's, highly optimized)
Single binary (no bootstrapping overhead)
Native TypeScript support (no transpile step)

Optimization Tips

Use bunfig.toml for config:

[run]
logLevel = "error"

Minimize imports — Each import has a cost
Use native modules — Bun's fs, path, etc.
Avoid transpilation — Bun handles TypeScript natively

6. Practical Workflows

Workflow 1: Monorepo Development

# Install all dependencies
bun install

# Run dev server for web app
bun --filter web run dev

# Run tests for changed packages
bun test --recursive

# Build everything
bun --filter "*" run build

Workflow 2: Creating CLI Tools

# Create new CLI package
mkdir packages/my-cli
cd packages/my-cli

# Create package.json with bin entry
cat > package.json << EOF
{
  "name": "@myapp/my-cli",
  "bin": {
    "my-cli": "./src/cli.ts"
  },
  "scripts": {
    "test": "bun test"
  }
}
EOF

# Back in root
bun install

# Test CLI from anywhere
bun my-cli --help

Workflow 3: Scripts and Utilities

# scripts/deploy.ts (executable)
#!/usr/bin/env bun
import { $ } from "bun";

const env = process.env.NODE_ENV || "staging";
console.log(`Deploying to ${env}...`);

await $`git push origin main`;
await $`bun --filter web run build`;
await $`vercel deploy --prod`;

console.log("✅ Deployed!");

# Run it
chmod +x scripts/deploy.ts
./scripts/deploy.ts

7. Integration Patterns

With Next.js

# bunx create-next-app + Bun
bunx create-next-app@latest my-app --bun
cd my-app

# Next.js + Bun
bun run dev
bun run build
bun start

With Vite

# Create Vite project
bunx create-vite@latest my-app --template react

cd my-app

# Use Bun
bun install
bun run dev
bun run build

With TypeScript

# No configuration needed
bun run my-script.ts

# Watch mode
bun --watch src/index.ts

# Type checking (in CI)
bunx tsc --noEmit

Common Pitfalls

❌ Don't

Use npm inside a Bun project — Use bun instead
Ignore bun.lockb — It's critical for reproducibility
Forget workspace protocol — Use workspace:* for local deps
Mix package managers — Stick to Bun (no npm, yarn, pnpm)
Assume Node.js compatibility — Most packages work, but test edge cases

✅ Do

Use bun install — Faster, lockb is optimized
Commit bun.lockb — It's tiny, git-friendly
Use bunx — For one-off commands
Leverage workspaces — For monorepos
Test with bun test — Native, no config needed

Checklist: Setting Up a Bun Project

Use bun create or bunx to scaffold
Run bun install (creates bun.lockb)
Add .bunfig.toml if custom config needed
Add bun.lockb to git
Use bun run for scripts
Use bun test for testing
Use bunx for one-off tools
Document Bun setup in README
Test on target Node version (if needed)

Performance Comparison

Task	Node.js	Bun
Startup	0.3s	0.08s
Install (100 packages)	45s	8s
Test run	2.3s	1.1s
Build (esbuild equiv.)	1.5s	0.4s

Bun is 4-10x faster for typical full-stack workflows.

Resources

Official Docs

Useful Commands

bun --help                 # All commands
bun install --help         # Install options
bun run --help             # Run options
bun test --help            # Test options

Related Skills

Bun CLI Development — Building CLIs with Bun
Monorepo Management — Advanced workspace patterns
Performance Optimization — Profiling and tuning
Git Workflows — Committing lockfiles reliably

FAQ

Q: Is Bun production-ready? A: Yes, for most use cases. Check Bun's compatibility for your specific packages.

Q: Should I switch from Node.js? A: For new projects, yes. For existing, evaluate package compatibility first.

Q: Will my npm packages work? A: Most do. Bun is npm-compatible. Test critical dependencies first.

Q: How do I handle CI/CD with Bun? A: Install Bun in CI, use bun install --frozen-lockfile, then bun run.

Q: Can I use Bun with monorepos? A: Absolutely. Workspaces make monorepos effortless.

Last Updated: 2025-12-05 Status: Reference Implementation Related: BUN_CLI_STANDARD.md, Bun Documentation

Install Skill

SKILL.md