​
Quick Start

Important: Select your backend configuration below. The setup steps differ depending on your choice. Following the wrong instructions may result in a broken setup.

​
Backend Configuration Options

Before proceeding: You need to choose your backend configuration. The setup steps differ depending on your choice.
Builder Box offers 4 different backend configurations. Hono + Bun is the default, but you can choose any option that fits your needs:
  • Backend: Hono web framework
  • Runtime: Bun (fast JavaScript runtime)
  • Structure: Separate server and web applications
  • Environment: Variables in separate files (server/.env and web/.env)
  • Performance: Excellent startup time and memory usage
  • 📖 Detailed Setup Guide

​
⚡ NextAPI + Node

  • Backend: Next.js API routes
  • Runtime: Node.js
  • Structure: API routes within Next.js app
  • Environment: Copy all variables from server/.env to web/.env
  • Performance: Standard Node.js performance
  • 📖 Detailed Setup Guide

​
🔧 Hono + Node

  • Backend: Hono web framework
  • Runtime: Node.js
  • Structure: Separate server and web applications
  • Environment: Variables in separate files
  • Performance: Good performance with Node.js
  • 📖 Detailed Setup Guide

​
🚀 NextAPI + Bun

  • Backend: Next.js API routes
  • Runtime: Bun (fast JavaScript runtime)
  • Structure: API routes within Next.js app
  • Environment: Copy all variables from server/.env to web/.env
  • Performance: Excellent startup time
  • 📖 Detailed Setup Guide

​
Choose Your Backend Configuration

Default Setup: If you’re new to Builder Box, we recommend starting with Hono + Bun (the default). It provides the best performance and simplest setup.
To continue with the setup, you need to:
  1. Review the options above and choose your preferred backend configuration
  2. Note the key differences in environment variable setup:
    • Hono backends: Environment variables go in separate files (server/.env and web/.env)
    • NextAPI backends: Copy ALL variables from server/.env to web/.env because API routes run within the Next.js app
  3. Follow the setup steps below with your chosen configuration in mind
Important: The setup instructions below work for all configurations, but pay special attention to the environment variable setup differences mentioned above.

​
Prerequisites

Before you begin, make sure you have these installed:
  • Bun v1.0+ (JavaScript runtime)
  • Git (version control)
  • Node.js 18+ (if not using Bun)

​
Step 1: Project Setup

​
1.1 Access Your Dashboard

Important: You need to purchase the Builder Box to access the dashboard. If you haven’t purchased it yet, you can buy it here: https://www.builderbox.ai/#pricing
  1. Visit the Dashboard
  2. Verify Access
    • Once logged in, you’ll see the main dashboard
    • This is where you can create and manage your projects
    Dashboard
  3. Create Your Project
    • Click the “Create Project” button on your dashboard
    • You’ll be prompted to fill out a project configuration form
  4. Configure Your Project
    • Project Name: Choose a descriptive name for your project
    • Description: Brief description of what you’re building
    • Template Options: Select your preferred configuration options
    • Answer any additional questions about your project setup
  5. Generate Project
    • Click “Create Project” to generate your custom boilerplate
    • Wait for the project generation to complete (this may take a moment)
    Project Dashboard
  6. Clone Your Project
    • After project creation, you’ll see a custom npm install command specific to your project
    • the command will look something like this: 
      npm install -g @humanoidz/builderbox && builderbox XXXXX
    • run the command to install the project
    • once the project is installed, you’ll see a message that the project is installed successfully
Project Dashboard
What happens next? After cloning, you’ll have a complete Builder Box project with all the code, but you still need to configure the various services (database, authentication, payments, etc.) in the following steps.

​
Step 2: Environment Configuration

Important Setup Difference: - For Hono backends: Environment variables go in separate files (server/.env and web/.env) - For NextAPI backends: Copy ALL variables from server/.env to web/.env because API routes run within the Next.js app

​
2.1 Database Setup (Supabase)

What is Supabase? It’s your PostgreSQL database hosting service.

​
Create Main Database

  1. Go to Supabase and sign up/login Supabase
  2. Create a new organization Supabase
  3. Create a new project
    • Choose a name for your project
    • Important: Save the database password - you’ll need it later Supabase
  4. Get your database connection strings:
    • Click “Connect” in the top center of your dashboard Supabase
    • Copy both connection strings:
      • Transaction pooler (for DATABASE_URL)
      • Session pooler (for DIRECT_URL) Supabase
  5. Add to apps/server/.env: 
    DATABASE_URL=your_transaction_pooler_url
DIRECT_URL=your_session_pooler_url

​
Create CMS Database

Why a separate database? The CMS needs its own database to keep content separate from your main app data.
  1. Create a second Supabase project following the same steps above
  2. Get the connection string (you only need one this time)
  3. Add to apps/cms/.env: 
    DATABASE_URI=your_cms_database_url

​
2.2 Authentication Setup

What is BetterAuth? It handles user login/signup, sessions, and OAuth integrations.

​
Generate Authentication Secret

  1. Generate a secure secret: 
    openssl rand -hex 16
  2. Add to apps/server/.env: 
    BETTER_AUTH_SECRET=your_generated_secret
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3001

​
Google OAuth Setup

Why Google OAuth? It allows users to sign in with their Google accounts.
  1. Visit Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable Google+ API:
    • Go to APIs & Services → Library
    • Search for “Google+ API” and enable it
  4. Set up OAuth credentials:
    • Go to APIs & Services → Credentials
    • Create OAuth 2.0 Client ID
    • Set these values:
      • Authorized JavaScript origins: http://localhost:3000, http://localhost:3001
      • Authorized redirect URIs: http://localhost:3000/api/auth/callback/google
  5. Watch this helpful video for detailed setup:
  6. Add to apps/server/.env: 
    GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

​
2.3 Email Service Setup (Resend)

What is Resend? It sends transactional emails like password resets and welcome emails.
  1. Visit Resend and sign up
  2. Create an API Key:
    • Go to API Keys section
    • Click “Create API Key”
    • Copy the key (starts with re_)
    Resend Resend Resend
  3. Add to apps/server/.env: 
    RESEND_API_KEY=re_your_api_key

​
2.4 Payment Setup (Stripe)

What is Stripe? It handles all payment processing, subscriptions, and billing.

​
Basic Stripe Setup

  1. Visit Stripe and login
  2. Enable Test Mode (toggle in top right) Stripe Test Mode Light
  3. Get your Secret Key:
    • Go to Developers → API Keys
    • Copy the Secret Key (starts with sk_test_)
    Stripe Secret Key Light
  4. Add to apps/server/.env: 
    STRIPE_SECRET_KEY=sk_test_your_secret_key
STRIPE_TEST_PRODUCT=price_your_price_id
Why webhooks? They notify your app when payments succeed or fail.
  1. Install ngrok (for local development): 
    # Follow instructions at https://ngrok.com/
ngrok http 3000
  2. In Stripe Dashboard:
    • Go to Developers → Webhooks → Add Endpoint
    • Enter your ngrok URL: https://your-ngrok-url.ngrok.io/api/webhooks/stripe
    • Select events or choose “Send all events”
    Stripe Endpoint Light
  3. Copy the Webhook Signing Secret and add to apps/server/.env: 
    STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

​
2.5 AI Integration (OpenRouter)

What is OpenRouter? It provides access to multiple AI models through a single API.
  1. Go to OpenRouter
  2. Create a new API key
  3. Copy the API key
OpenRouter API Key Light
  1. Add to apps/server/.env: 
    OPENROUTER_API_KEY=your_openrouter_api_key

​
2.6 CMS Secret Generation

What is the CMS? It’s your content management system for blog posts, pages, etc.
  1. Generate a secure secret: 
    openssl rand -hex 32
  2. Add to apps/cms/.env: 
    PAYLOAD_SECRET=your_generated_cms_secret

​
2.7 Frontend Configuration

Configure the frontend app to connect to your backend services. Add to apps/web/.env: 
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3001
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3003

# For NextAPI backends, also include ALL variables from server/.env

​
Step 3: Database Migration

Set up your database tables using Prisma (database toolkit).

​
3.1 Run Database Setup

# Navigate to server directory
cd apps

# Generate Prisma client (creates database connection code)
bun run db:generate

# Create initial migration (sets up database structure)
bun run db:migrate

# Push schema changes to database (applies the structure)
bun run db:push
What these commands do: - prisma generate: Creates the database client code - prisma migrate dev: Creates and applies database migrations - prisma db push: Ensures all schema changes are applied

​
Step 4: Launch Your App! 🚀

​
4.1 Start All Services

Since this is a turborepo project, you can start all services with a single command: 
# From the root directory
bun dev
This will automatically start:
  • Backend Server on port 3000
  • Frontend App on port 3001
  • CMS on port 3003
Turborepo Magic: The bun dev command runs all three services in parallel automatically. You’ll see logs from all services in one terminal window.

​
4.2 Alternative: Individual Services

If you prefer to run services separately (for debugging or development), you can use individual terminals:

​
4.3 Access Your Apps

​
Environment Variables Summary

Here’s a complete overview of all the environment variables you should have configured:

​
Server Environment (apps/server/.env)

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

​
Web Environment (apps/web/.env)

NEXT_PUBLIC_SERVER_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3001
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3003

# For NextAPI backends, also include ALL variables from server/.env

​
CMS Environment (apps/cms/.env)

DATABASE_URI=your_cms_supabase_url
PAYLOAD_SECRET=your_generated_cms_secret

​
Troubleshooting

​
Common Issues

🔥 “Database connection failed”
  • Double-check your Supabase connection strings
  • Ensure your database is running
  • Verify you copied the correct pooler URLs
🔥 “Authentication not working”
  • Make sure your Google OAuth URLs are correct
  • Check that your BETTER_AUTH_SECRET is properly set
  • Verify Google+ API is enabled
🔥 “Payments not processing”
  • Ensure you’re in Stripe test mode
  • Check that your webhook endpoint is correct
  • Verify your product price ID is accurate
🔥 “Port already in use”
  • Kill existing processes: lsof -ti:3000 | xargs kill -9
  • Or use different ports in your environment variables

​
Next Steps

🎉 Congratulations! Your Builder Box is now running. Here’s what you can do next:
  1. Customize the frontend - Edit components in apps/web/src/components
  2. Add API endpoints - Create new routes in apps/server/src/routes
  3. Configure CMS - Add content types in apps/cms/src/collections
  4. Set up production - Deploy to Vercel, Railway, or your preferred platform
  5. Add features - Extend with additional integrations and functionality
Happy building! 🚀