Refactor code structure and remove redundant changes

migration/BUN_GUIDE.md

@@ -0,0 +1,523 @@
+# 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