Bun Development

Complete guide to development with Bun build system, TypeScript tooling, and package management.

When to use this skill

Use this skill when:

• Setting up a new Bun project

• Configuring TypeScript with Bun

• Building a project with Bun

• Managing dependencies with bun install/bun pm

• Using dev mode for hot reloading

• Running type checking with tsc --noEmit

• Creating production builds with bun run build

Bun Build System

Core Concepts

Bun is a fast JavaScript runtime and package manager with native TypeScript support.

Key Benefits:

• Fast: JavaScript runtime written in Rust, ~10x faster than Node.js

• Native TypeScript: Built-in TypeScript support, no transpilation needed

• All-in-One: Runtime and package manager combined

• Compatible: Works with existing npm/yarn/pnpm workspaces

• Minimal: Zero-config, fast install, efficient caching

Project Structure

Bun projects follow this structure:

project/ ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── src/ # Source TypeScript files ├── test/ # Test files └── dist/ # Compiled output (production)

Development Mode

Use bun run dev for hot reloading during development:

Start development server with hot reload

bun run dev

Watch TypeScript files and recompile on changes

bun run dev --watch

Dev Mode Features:

• Live reload on file changes

• Source maps for debugging

• Faster rebuild times than tsc

• Native TypeScript execution

TypeScript Configuration

tsconfig.json Best Practices

Recommended configuration for Bun projects:

{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "lib": ["ES2022"], "moduleResolution": "bundler", "resolveJsonModule": true, "allowImportingTsExtensions": true, "noEmit": true, "sourceMap": true, "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "paths": { "@/": ["./src/"] } }, "exclude": ["node_modules", "dist"] }

Type Checking

NO TSC POLICY: Never use tsc for building with Bun. Use bun run build only.

Type checking uses tsc --noEmit for validation:

Type check only (no compilation)

bun run type-check

Type check with watch mode

bun run type-check --watch

Common Type Checking Issues:

• Missing imports: @types/package-name

• Implicit any types: Avoid, use explicit types

• Strict null checks: Enable strict mode for safety

Package Management

Installing Dependencies

Use bun install instead of npm/yarn:

Install dependencies

bun install

Install specific package

bun install package-name

Install with devDependencies

bun install --dev

Install exact version

bun install package-name@1.2.3

Bun Install Benefits:

• Fast downloads (concurrent package fetching)

• Efficient caching

• Lock file: bun.lock for reproducible installs

• Workspace support

• Compatible with npm registries

Package.json Scripts

Recommended scripts for Bun projects:

{ "scripts": { "dev": "bun run --hot", # Hot reload dev server "build": "bun build", # Production build "type-check": "tsc --noEmit", # Type checking "test": "bun test", # Run tests "lint": "eslint .", # Lint code "format": "prettier --write .", # Format code "clean": "rm -rf dist", # Clean build artifacts "prepublishOnly": "bun run type-check" # Type check before publishing } }

Managing Workspaces

For monorepos, use workspaces:

{ "workspaces": ["packages/", "apps/"] }

Install workspace dependencies:

Install all workspace deps

bun install

Add specific workspace package

bun add @scope/package --workspace apps/my-app

Development Workflow

Setting Up a New Project

Initialize project:

bun init -y

Install dependencies:

bun install

Configure TypeScript:

Copy recommended tsconfig from Bun

Or use bunx create-react-app for scaffolding

Start development:

Use dev mode for hot reloading

bun run dev

Daily Development Loop

Recommended workflow:

1. Write code
2. Type check: bun run type-check
3. Fix type errors
4. Run tests: bun test
5. Lint: bun run lint
6. Format: bun run format
7. Commit changes (using Git or liaison task)
8. Repeat

Hot Reloading

Bun's dev mode provides live reloading:

Start dev server

bun run dev

Features:

• File watching
• Live compilation
• HMR (Hot Module Replacement)
• Source maps

Production Build

Building for Deployment

NO TSC!: Use bun run build , never tsc for compilation.

Production build

bun run build

Build for specific target

bun run build --target node

Build with environment variables

NODE_ENV=production bun run build

Before Deploying

Checklist:

• All tests passing: bun test

• Type check clean: bun run type-check

• Linting passes: bun run lint

• Build output verified: ls dist/

• Environment variables configured

• Dependencies up-to-date: bun update

Deployment Options

Bun can produce various outputs:

Build for Node.js (CommonJS)

bun build --target node

Build for Node.js (ESM)

bun build --target node --module ESNext

Build for browsers

bun build --target browser

Bun vs Other Runtimes

Node.js Comparison

Feature Bun Node.js

Speed 10-20x faster Baseline

Startup ~50-100ms faster Baseline

Memory Lower Higher (V8)

TS Support Native Requires tsc

Bun vs Deno

Feature Bun Deno

TypeScript Native (fast) Native

Package Manger Built-in Native

Web APIs Built-in No fetch API

Stability Production Alpha

Common Patterns

Environment Detection

const isBun = process.versions.bun !== undefined;

// Conditional imports if (isBun) { const bun = await import('bun'); } else { const node = await import('node'); }

Fast Development Commands

Install and run immediately

bun install --hot

Create new project with templates

bunx create-vite-app

Run tests in watch mode

bun test --watch

Type check continuously

bun run type-check --watch

Migration from npm/yarn

Quick start for existing projects:

• Replace npm with bun in scripts

• Run bun install

• Use bun run for scripts

• Type checking: bun run type-check

Package manager aliases in package.json:

{ "scripts": { "build": "bun build", "dev": "bun run --hot", "type-check": "tsc --noEmit" }, "packageManager": "bun" }

Troubleshooting

Common Issues

Build fails or produces no output:

• Check tsconfig.json outDir is set to dist/

• Verify sourceMap: true is enabled

• Run with verbose flag: bun run build --verbose

Type checking not finding files:

• Verify tsconfig.json include patterns match your files

• Check exclude patterns aren't too broad

• Run with absolute paths if needed: bun run type-check /path/to/project

Hot reloading not working:

• Verify you're in project root with package.json

• Check dev server is running: bun run dev

• Try stopping and restarting dev server

• Check firewall allows dev server port

Module resolution fails:

• Use moduleResolution: "bundler" in tsconfig.json

• For workspace projects, ensure paths alias is set correctly

• Verify dependencies are installed in root workspace

Best Practices

1. Always Use bun run build for Production

NO TSC! NEVER use tsc for building. Bun's TypeScript compiler is faster and handles ESM natively.

❌ WRONG

tsc # Will create ESM that fails in Node

✅ CORRECT

bun run build # Proper Bun compilation

2. Type Check During Development

Use bun run type-check (which runs tsc --noEmit ) for validation only:

Continuous type checking

bun run type-check --watch

3. Leverage Hot Reload

Use bun run dev for fast development cycles:

Development with hot reload

bun run dev

Edit source → Automatic recompile

Test immediately

4. Install Dependencies with Bun

Replace npm with bun for speed:

Standard install

bun install

Install with devDependencies

bun install --dev

Update lock file

bun install

5. Use bunx for Scaffolding

Create projects quickly with community templates:

Create React app

bunx create-react-app my-app

Create Vite project

bunx create-vite my-app

Create Bun-native project

bunx create-bun-app

Examples

Example 1: Setting Up a New Bun Project

Initialize

bun init -y

Install dependencies

bun install typescript @types/node

Create tsconfig.json

cat > tsconfig.json << 'EOF' { "compilerOptions": { "target": "ES2022", "module": "ESNext", "noEmit": true, "strict": true } } EOF

Install dev dependencies

bun install --dev @types/vitest

Start development

bun run dev

Example 2: Migration from npm

Before (package.json):

{ "scripts": { "build": "tsc", "dev": "node index.js" } }

After (migrated to Bun):

{ "scripts": { "build": "bun build", "dev": "bun run --hot" "type-check": "tsc --noEmit" } }

Example 3: Production Build

Type check first

bun run type-check

Then build for production

bun run build

Verify build output

ls -la dist/

Deploy

bun run deploy # (if configured)

References

Official Documentation

• Bun Docs: https://bun.sh/docs

• TypeScript in Bun: https://bun.sh/docs/runtime/typescript

• Bun Package Manager: https://bun.sh/docs/runtime/package-manager

• CLI Reference: https://bun.sh/docs/cli

Related Skills

• Git Automation (.skills/git-automation/SKILL.md) - Workflow automation with Git

• Liaison Workflows (.skills/liaison-workflows/SKILL.md) - Task management patterns

Keywords

bun, typescript, build, development, package-manager, dev, hot-reload, type-check, production, esm, vite, nest, next.js, react