thrilltrack-explorer/migration/BUN_GUIDE.md

# Bun Setup & Usage Guide

**For:** ThrillWiki Next.js 15 Migration  
**Last Updated:** November 9, 2025

---

## 🎯 Overview

Bun is an all-in-one JavaScript runtime & toolkit that replaces Node.js, npm, yarn, and webpack. It's significantly faster than traditional tools and is the official package manager for this migration.

**Why Bun?**
- ⚡ 25x faster than npm
- 🚀 Fast startup times
- 📦 All-in-one (runtime + bundler + package manager)
- 🔄 Drop-in replacement for Node.js/npm
- ✅ Compatible with Next.js 15

---

## 📥 Installation

### macOS & Linux

```bash
curl -fsSL https://bun.sh/install | bash
```

### Windows (WSL2)

```bash
curl -fsSL https://bun.sh/install | bash
```

### Verify Installation

```bash
bun --version
# Should output: 1.x.x
```

---

## 🚀 Basic Commands

### Package Management

```bash
# Install dependencies from package.json
bun install

# Install a specific package
bun add <package-name>

# Install as dev dependency
bun add -d <package-name>

# Install globally
bun add -g <package-name>

# Remove a package
bun remove <package-name>

# Update packages
bun update

# Update a specific package
bun update <package-name>
```

### Running Scripts

```bash
# Run a package.json script
bun run dev
bun run build
bun run start
bun run test

# Or shorter (bun run is optional)
bun dev
bun build
bun start
bun test
```

### Running Files

```bash
# Run a TypeScript/JavaScript file directly
bun index.ts
bun server.js

# Run with watch mode (auto-restart on changes)
bun --watch index.ts
```

---

## 📦 Common ThrillWiki Commands

### Development

```bash
# Start Next.js development server with Turbopack
bun run dev

# Or shorter
bun dev

# Expected output:
# ▲ Next.js 15.x.x
# - Local:        http://localhost:3000
# - Turbopack:    ✓ Enabled
```

### Building

```bash
# Create production build
bun run build

# This will:
# 1. Compile TypeScript
# 2. Build Next.js pages
# 3. Optimize bundles
# 4. Generate static pages (ISR/SSG)
```

### Production

```bash
# Start production server (after build)
bun run start

# Server will run on http://localhost:3000
```

### Type Checking

```bash
# Run TypeScript compiler
bun run type-check

# This runs: tsc --noEmit
```

### Linting

```bash
# Run ESLint
bun run lint

# Fix auto-fixable issues
bun run lint --fix
```

### Testing

```bash
# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Run tests with coverage
bun test --coverage
```

---

## 🔧 Project Setup

### Initialize New Next.js Project

```bash
# Create new Next.js 15 project with Bun
bun create next-app@latest my-project --typescript --tailwind --app

cd my-project
```

### Migrate Existing Project to Bun

```bash
# Remove old lock files
rm package-lock.json
rm yarn.lock
rm pnpm-lock.yaml

# Install with Bun
bun install

# This creates bun.lockb
```

---

## ⚙️ Configuration

### package.json Scripts

Update your `package.json` scripts to use Bun:

```json
{
  "scripts": {
    "dev": "next dev --turbo",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit",
    "test": "vitest"
  }
}
```

### .bunfig.toml (Optional)

Create `.bunfig.toml` in project root for Bun configuration:

```toml
# Bun configuration

[install]
# Use exact versions (like npm's --exact)
exact = true

# Cache directory
cache = ".bun-cache"

# Optional: Configure registry
# registry = "https://registry.npmjs.org"

[test]
# Test configuration
coverage = true
```

---

## 🔄 NPM to Bun Command Mapping

| NPM Command | Bun Command | Description |
|------------|-------------|-------------|
| `npm install` | `bun install` | Install dependencies |
| `npm install <pkg>` | `bun add <pkg>` | Add package |
| `npm install -D <pkg>` | `bun add -d <pkg>` | Add dev dependency |
| `npm uninstall <pkg>` | `bun remove <pkg>` | Remove package |
| `npm run <script>` | `bun run <script>` | Run script |
| `npm run <script>` | `bun <script>` | Run script (shorter) |
| `npm update` | `bun update` | Update packages |
| `npm ci` | `bun install --frozen-lockfile` | Clean install |
| `npm test` | `bun test` | Run tests |
| `npx <cmd>` | `bunx <cmd>` | Execute package |

---

## 🎨 Bun with Next.js 15

### Development Server

```bash
# Start with Turbopack (Next.js 15)
bun dev

# Features:
# - Hot Module Replacement (HMR)
# - Fast Refresh
# - TypeScript compilation
# - CSS/Tailwind compilation
```

### Environment Variables

Bun reads `.env.local` automatically:

```bash
# .env.local
NEXT_PUBLIC_DJANGO_API_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_CLOUDFLARE_ACCOUNT_ID=xxx
```

Access in code:

```typescript
const apiUrl = process.env.NEXT_PUBLIC_DJANGO_API_URL;
```

---

## 🧪 Testing with Bun

### Vitest Setup

```bash
# Install Vitest
bun add -d vitest @testing-library/react @testing-library/jest-dom
```

### vitest.config.ts

```typescript
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './'),
    },
  },
});
```

### Run Tests

```bash
bun test
```

---

## 🚨 Common Issues & Solutions

### Issue: `bun: command not found`

**Solution:**
```bash
# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

# Or restart terminal
```

### Issue: Package installation fails

**Solution:**
```bash
# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install
```

### Issue: Next.js dev server won't start

**Solution:**
```bash
# Check port 3000 is free
lsof -i :3000

# Kill process if needed
kill -9 <PID>

# Restart dev server
bun dev
```

### Issue: TypeScript errors after installing packages

**Solution:**
```bash
# Regenerate types
bun run type-check

# Or restart TS server in VS Code
# Cmd+Shift+P → "TypeScript: Restart TS Server"
```

### Issue: Bun vs Node.js compatibility

Some packages may not work with Bun yet. Use Node.js fallback:

```bash
# Run with Node.js instead
node --loader tsx index.ts

# Or use NODE_ENV
NODE_ENV=production node index.js
```

---

## 📊 Performance Comparison

### Install Speed

```bash
# NPM
time npm install  # ~45s

# Yarn
time yarn install  # ~35s

# Bun
time bun install  # ~2s ⚡
```

### Script Execution

```bash
# NPM
time npm run build  # ~120s

# Bun
time bun run build  # ~90s
```

---

## 🔗 Advanced Usage

### Workspaces (Monorepo)

```json
// package.json
{
  "workspaces": ["packages/*"]
}
```

```bash
# Install all workspace dependencies
bun install

# Run script in specific workspace
bun --filter my-package run build
```

### Custom Scripts

```typescript
// scripts/build.ts
import { $ } from 'bun';

console.log('Building project...');

await $`bun run type-check`;
await $`bun run lint`;
await $`next build`;

console.log('✅ Build complete!');
```

Run:

```bash
bun scripts/build.ts
```

---

## 🎯 Best Practices

### 1. Use Exact Versions

Add to `.bunfig.toml`:

```toml
[install]
exact = true
```

### 2. Commit Lock File

Always commit `bun.lockb` to version control:

```bash
git add bun.lockb
git commit -m "Update dependencies"
```

### 3. Use Scripts

Define common tasks in `package.json`:

```json
{
  "scripts": {
    "dev": "next dev --turbo",
    "build": "next build",
    "start": "next start",
    "clean": "rm -rf .next node_modules bun.lockb"
  }
}
```

### 4. Regular Updates

Keep Bun updated:

```bash
bun upgrade
```

---

## 📚 Resources

- Official Documentation: https://bun.sh/docs
- GitHub: https://github.com/oven-sh/bun
- Discord: https://bun.sh/discord
- Next.js + Bun: https://nextjs.org/docs/app/building-your-application/configuring/bun

---

## 🔗 Related Documentation

- [Phase 1: Foundation](./PHASE_01_FOUNDATION.md)
- [Environment Variables Guide](./ENVIRONMENT_VARIABLES.md)
- [Next.js 15 Migration Guide](./NEXTJS_15_MIGRATION_GUIDE.md)

---

**Document Version:** 1.0  
**Last Updated:** November 9, 2025