pacnpal/thrilltrack-explorer

Fork 0

mirror of https://github.com/pacnpal/thrilltrack-explorer.git synced 2025-12-20 10:31:13 -05:00

Files

pacnpal eb68cf40c6 Refactor code structure and remove redundant changes

2025-11-09 16:31:34 -05:00

7.9 KiB

Raw Blame History

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

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

Windows (WSL2)

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

Verify Installation

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

🚀 Basic Commands

Package Management

# 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

# 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

# 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

# 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

# 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

# Start production server (after build)
bun run start

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

Type Checking

# Run TypeScript compiler
bun run type-check

# This runs: tsc --noEmit

Linting

# Run ESLint
bun run lint

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

Testing

# 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

# 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

# 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:

{
  "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:

# 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

# 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:

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

Access in code:

const apiUrl = process.env.NEXT_PUBLIC_DJANGO_API_URL;

🧪 Testing with Bun

Vitest Setup

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

vitest.config.ts

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

bun test

🚨 Common Issues & Solutions

Issue: `bun: command not found`

Solution:

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

# Or restart terminal

Issue: Package installation fails

Solution:

# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install

Issue: Next.js dev server won't start

Solution:

# 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:

# 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:

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

# Or use NODE_ENV
NODE_ENV=production node index.js

📊 Performance Comparison

Install Speed

# NPM
time npm install  # ~45s

# Yarn
time yarn install  # ~35s

# Bun
time bun install  # ~2s ⚡

Script Execution

# NPM
time npm run build  # ~120s

# Bun
time bun run build  # ~90s

🔗 Advanced Usage

Workspaces (Monorepo)

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

# Install all workspace dependencies
bun install

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

Custom Scripts

// 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:

bun scripts/build.ts

🎯 Best Practices

1. Use Exact Versions

Add to .bunfig.toml:

[install]
exact = true

2. Commit Lock File

Always commit bun.lockb to version control:

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

3. Use Scripts

Define common tasks in package.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:

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

Document Version: 1.0
Last Updated: November 9, 2025

7.9 KiB Raw Blame History

Bun Setup & Usage Guide

🎯 Overview

📥 Installation

macOS & Linux

Windows (WSL2)

Verify Installation

🚀 Basic Commands

Package Management

Running Scripts

Running Files

📦 Common ThrillWiki Commands

Development

Building

Production

Type Checking

Linting

Testing

🔧 Project Setup

Initialize New Next.js Project

Migrate Existing Project to Bun

⚙️ Configuration

package.json Scripts

.bunfig.toml (Optional)

🔄 NPM to Bun Command Mapping

🎨 Bun with Next.js 15

Development Server

Environment Variables

🧪 Testing with Bun

Vitest Setup

vitest.config.ts

Run Tests

🚨 Common Issues & Solutions

Issue: bun: command not found

Issue: Package installation fails

Issue: Next.js dev server won't start

Issue: TypeScript errors after installing packages

Issue: Bun vs Node.js compatibility

📊 Performance Comparison

Install Speed

Script Execution

🔗 Advanced Usage

Workspaces (Monorepo)

Custom Scripts

🎯 Best Practices

1. Use Exact Versions

2. Commit Lock File

3. Use Scripts

4. Regular Updates

📚 Resources

🔗 Related Documentation

7.9 KiB

Raw Blame History

Issue: `bun: command not found`