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:

🚀 Hono + Bun (Default) - Recommended

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:

Review the options above and choose your preferred backend configuration
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
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

Visit the Dashboard
- Go to: https://www.builderbox.ai/bought/main
- Log in with your account credentials
Verify Access
- Once logged in, you’ll see the main dashboard
- This is where you can create and manage your projects
Create Your Project
- Click the “Create Project” button on your dashboard
- You’ll be prompted to fill out a project configuration form
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
Generate Project
- Click “Create Project” to generate your custom boilerplate
- Wait for the project generation to complete (this may take a moment)
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

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

Go to Supabase and sign up/login
Create a new organization
Create a new project
- Choose a name for your project
- Important: Save the database password - you’ll need it later
Get your database connection strings:
- Click “Connect” in the top center of your dashboard
- Copy both connection strings:
  - Transaction pooler (for DATABASE_URL)
  - Session pooler (for DIRECT_URL)

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.

Create a second Supabase project following the same steps above
Get the connection string (you only need one this time)
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

Generate a secure secret:
openssl rand -hex 16

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.

Visit Google Cloud Console
Create a new project or select an existing one
Enable Google+ API:
- Go to APIs & Services → Library
- Search for “Google+ API” and enable it
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
Watch this helpful video for detailed setup:

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.

Visit Resend and sign up
Create an API Key:
- Go to API Keys section
- Click “Create API Key”
- Copy the key (starts with re_)
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

Visit Stripe and login
Enable Test Mode (toggle in top right)
Get your Secret Key:
- Go to Developers → API Keys
- Copy the Secret Key (starts with sk_test_)

Add to apps/server/.env:

STRIPE_SECRET_KEY=sk_test_your_secret_key
STRIPE_TEST_PRODUCT=price_your_price_id

Webhook Setup (Optional but Recommended)

Why webhooks? They notify your app when payments succeed or fail.

Install ngrok (for local development):

# Follow instructions at https://ngrok.com/
ngrok http 3000

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”
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.

Go to OpenRouter
Create a new API key
Copy the API key

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.

Generate a secure secret:
openssl rand -hex 32

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

Frontend: http://localhost:3001
Backend API: http://localhost:3000
CMS: http://localhost:3003

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:

Customize the frontend - Edit components in apps/web/src/components
Add API endpoints - Create new routes in apps/server/src/routes
Configure CMS - Add content types in apps/cms/src/collections
Set up production - Deploy to Vercel, Railway, or your preferred platform
Add features - Extend with additional integrations and functionality

Happy building! 🚀

​Quick Start

​Backend Configuration Options

​🚀 Hono + Bun (Default) - Recommended

​⚡ NextAPI + Node

​🔧 Hono + Node

​🚀 NextAPI + Bun

​Choose Your Backend Configuration

​Prerequisites

​Step 1: Project Setup

​1.1 Access Your Dashboard

​Step 2: Environment Configuration

​2.1 Database Setup (Supabase)

​Create Main Database

​Create CMS Database

​2.2 Authentication Setup

​Generate Authentication Secret

​Google OAuth Setup

​2.3 Email Service Setup (Resend)

​2.4 Payment Setup (Stripe)

​Basic Stripe Setup

​Webhook Setup (Optional but Recommended)

​2.5 AI Integration (OpenRouter)

​2.6 CMS Secret Generation

​2.7 Frontend Configuration

​Step 3: Database Migration

​3.1 Run Database Setup

​Step 4: Launch Your App! 🚀

​4.1 Start All Services

​4.2 Alternative: Individual Services

​4.3 Access Your Apps

​Environment Variables Summary

​Server Environment (apps/server/.env)

​Web Environment (apps/web/.env)

​CMS Environment (apps/cms/.env)

​Troubleshooting

​Common Issues

​Next Steps

Quick Start

Backend Configuration Options

🚀 Hono + Bun (Default) - Recommended

⚡ NextAPI + Node

🔧 Hono + Node

🚀 NextAPI + Bun

Choose Your Backend Configuration

Prerequisites

Step 1: Project Setup

1.1 Access Your Dashboard

Step 2: Environment Configuration

2.1 Database Setup (Supabase)

Create Main Database

Create CMS Database

2.2 Authentication Setup

Generate Authentication Secret

Google OAuth Setup

2.3 Email Service Setup (Resend)

2.4 Payment Setup (Stripe)

Basic Stripe Setup

Webhook Setup (Optional but Recommended)

2.5 AI Integration (OpenRouter)

2.6 CMS Secret Generation

2.7 Frontend Configuration

Step 3: Database Migration

3.1 Run Database Setup

Step 4: Launch Your App! 🚀

4.1 Start All Services

4.2 Alternative: Individual Services

4.3 Access Your Apps

Environment Variables Summary

Server Environment (`apps/server/.env`)

Web Environment (`apps/web/.env`)

CMS Environment (`apps/cms/.env`)

Troubleshooting

Common Issues

Next Steps