NextAPI + Bun Setup

​

What You’ll Get

• Backend: Next.js API routes
• Runtime: Bun (fast JavaScript runtime)
• Bundler: Bun’s built-in bundler
• Performance: Excellent startup time
• Structure: API routes within Next.js app

​

Prerequisites

• Bun v1.0+ installed
• Git for version control
• Access to your Builder Box dashboard

​

Step 1: Project Setup

​

1.1 Access Your Dashboard

1. Visit the Dashboard
   • Go to: https://www.builderbox.ai/bought/main
   • Log in with your account credentials
2. Create Your Project
   • Click “Create Project” on your dashboard
   • Select “NextAPI + Bun” as your backend configuration
   • Fill out the project configuration form
   • Click “Create Project” to generate your boilerplate
3. Install Your Project
   • Run the provided installation command:
     Copy

     npm install -g @humanoidz/builderbox && builderbox YOUR_PROJECT_ID
     

​

Step 2: Environment Configuration

​

2.1 Web Environment Variables (Combined)

# Database
DATABASE_URL=your_supabase_transaction_pooler_url
DIRECT_URL=your_supabase_session_pooler_url

# Authentication
BETTER_AUTH_SECRET=your_generated_secret
BETTER_AUTH_URL=http://localhost:3001
CORS_ORIGIN=http://localhost:3001

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Email
RESEND_API_KEY=re_your_api_key

# Payments
STRIPE_SECRET_KEY=sk_test_your_secret_key
STRIPE_TEST_PRODUCT=price_your_price_id
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

# AI
OPENROUTER_API_KEY=your_openrouter_api_key

# Frontend Configuration
NEXT_PUBLIC_SERVER_URL=http://localhost:3001
NEXT_PUBLIC_APP_URL=http://localhost:3001
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3003

​

2.2 CMS Environment Variables

DATABASE_URI=your_cms_supabase_url
PAYLOAD_SECRET=your_generated_cms_secret

​

Step 3: Database Setup

​

3.1 Run Database Commands

# Navigate to the project root
cd your-project-name

# Generate Prisma client
bun run db:generate

# Create initial migration
bun run db:migrate

# Push schema changes
bun run db:push

​

Step 4: Start Development

​

4.1 Start All Services

# From the root directory
bun dev

• Frontend App (Next.js + API routes) on port 3001
• CMS on port 3003

​

4.2 Individual Services (Optional)

cd apps/web
bun dev

cd apps/cms
bun dev

​

Step 5: Verify Setup

​

5.1 Check Services

• Frontend + API: http://localhost:3001
• CMS: http://localhost:3003

​

5.2 Test API Endpoints

# Health check
curl http://localhost:3001/api/trpc/healthCheck

# Should return: {"message":"OK"}

​

Project Structure

your-project/
├── apps/
│   ├── web/             # Next.js frontend + API routes
│   │   ├── src/
│   │   │   ├── app/     # Next.js app router
│   │   │   │   └── api/ # API routes
│   │   │   └── lib/     # Utilities
│   │   └── package.json
│   └── cms/             # Payload CMS
│       ├── src/
│       └── package.json
├── packages/            # Shared packages
└── package.json         # Root package.json

​

Key Features

​

Next.js API Routes Benefits

• Unified Codebase: Frontend and backend in one project
• Type Safety: Full TypeScript support
• Middleware: Next.js middleware support
• Deployment: Easy deployment to Vercel
• Familiarity: Standard Next.js patterns

​

Bun Runtime Benefits

• Speed: Faster startup and execution
• Memory: Lower memory usage
• Bundler: Built-in bundler for production builds
• Compatibility: Full Node.js compatibility
• Developer Experience: Fast package installation

​

Development Commands

​

Environment Variables Management

​

Important Notes

1. Single Environment File: All variables are in apps/web/.env
2. API Routes Access: Environment variables are accessible in API routes
3. Client Variables: Use NEXT_PUBLIC_ prefix for client-side variables
4. Security: Never expose sensitive variables to the client

​

Variable Categories

# Server-side only (not exposed to client)
DATABASE_URL=...
BETTER_AUTH_SECRET=...
STRIPE_SECRET_KEY=...

# Client-side accessible
NEXT_PUBLIC_APP_URL=...
NEXT_PUBLIC_SERVER_URL=...

​

Performance Benefits

​

Bun vs Node.js for Next.js

​

Optimization Tips

1. Use Bun’s Built-in Bundler:
   Copy

   # Faster builds with Bun
   bun run build
   

2. Leverage Bun’s Package Manager:
   Copy

   # Faster package installation
   bun install
   

3. Enable Bun’s Optimizations:
   Copy

   // Use Bun's native APIs where possible
   const file = Bun.file("data.json");
   const data = await file.json();
   

​

Troubleshooting

​

Common Issues

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

• Ensure all variables are in apps/web/.env
• Check for typos in variable names
• Restart the development server

# Kill existing processes
lsof -ti:3001 | xargs kill -9

• Verify your Supabase connection strings
• Ensure your database is running
• Check environment variables in apps/web/.env

• Verify Google OAuth configuration
• Check BETTER_AUTH_SECRET is set
• Ensure CORS_ORIGIN is correct

# Clear cache and reinstall
rm -rf node_modules
bun install

​

Migration from Node.js

1. Update Package Manager:
   Copy

   # Replace npm commands with bun
   npm install → bun install
   npm run dev → bun dev
   

2. Update Scripts:
   Copy

   {
     "scripts": {
       "dev": "bun --bun next dev",
       "build": "bun --bun next build",
       "start": "bun --bun next start"
     }
   }
   

3. Install Bun:
   Copy

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

​

Deployment Considerations

​

Vercel Deployment

1. Connect to Vercel:
   Copy

   npm install -g vercel
   vercel
   

2. Environment Variables:
   • Add all variables to Vercel dashboard
   • Use NEXT_PUBLIC_ prefix for client variables
3. Build Configuration:
   Copy

   {
     "buildCommand": "bun run build",
     "installCommand": "bun install"
   }
   

​

Other Platforms

• Railway: Supports Bun runtime
• DigitalOcean App Platform: Supports Bun
• Docker: Use Bun base image

​

Next Steps

1. Customize the frontend - Edit components in apps/web/src/components
2. Add API endpoints - Create new routes in apps/web/src/app/api
3. Configure CMS - Add content types in apps/cms/src/collections
4. Set up production - Deploy to Vercel for optimal performance
5. Add features - Extend with additional integrations