> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builderbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Quick Start
> Spin up your Builder Box project in minutes with this step-by-step guide.
## 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](/backend-options/hono-bun)**
### âš¡ **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](/backend-options/nextapi-node)**
### 🔧 **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](/backend-options/hono-node)**
### 🚀 **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](/backend-options/nextapi-bun)**
***
## 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](https://bun.sh) v1.0+ (JavaScript runtime)
* [Git](https://git-scm.com/) (version control)
* [Node.js](https://nodejs.org/en) 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](https://www.builderbox.ai/#pricing)
1. **Visit the Dashboard**
* Go to: [https://www.builderbox.ai/bought/main](https://www.builderbox.ai/bought/main)
* Log in with your account credentials
2. **Verify Access**
* Once logged in, you'll see the main dashboard
* This is where you can create and manage your projects
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)
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:
```bash theme={null}
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
1. **Go to [Supabase](https://app.supabase.com)** and sign up/login
2. **Create a new organization**
3. **Create a new project**
* Choose a name for your project
* **Important:** Save the database password - you'll need it later
4. **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)
5. **Add to `apps/server/.env`:**
```env theme={null}
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`:**
```env theme={null}
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:**
```bash theme={null}
openssl rand -hex 16
```
2. **Add to `apps/server/.env`:**
```env theme={null}
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](https://console.cloud.google.com)**
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`:**
```env theme={null}
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](https://resend.com)** and sign up
2. **Create an API Key:**
* Go to API Keys section
* Click "Create API Key"
* Copy the key (starts with `re_`)
3. **Add to `apps/server/.env`:**
```env theme={null}
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](https://stripe.com)** and login
2. **Enable Test Mode** (toggle in top right)
3. **Get your Secret Key:**
* Go to Developers → API Keys
* Copy the Secret Key (starts with `sk_test_`)
4. **Add to `apps/server/.env`:**
```env theme={null}
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.
1. **Install ngrok** (for local development):
```bash theme={null}
# 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"
3. **Copy the Webhook Signing Secret and add to `apps/server/.env`:**
```env theme={null}
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](https://openrouter.ai/settings/keys)**
2. **Create a new API key**
3. **Copy the API key**
4. **Add to `apps/server/.env`:**
```env theme={null}
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:**
```bash theme={null}
openssl rand -hex 32
```
2. **Add to `apps/cms/.env`:**
```env theme={null}
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`:**
```env theme={null}
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
```bash theme={null}
# 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:
```bash theme={null}
# 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:
Click to see individual terminal commands
**Terminal 1 - Backend Server:**
```bash theme={null}
cd apps/server
bun dev
```
**Terminal 2 - Frontend App:**
```bash theme={null}
cd apps/web
bun dev
```
**Terminal 3 - CMS:**
```bash theme={null}
cd apps/cms
bun dev
```
### 4.3 Access Your Apps
* **Frontend:** [http://localhost:3001](http://localhost:3001)
* **Backend API:** [http://localhost:3000](http://localhost:3000)
* **CMS:** [http://localhost:3003](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`)
```env theme={null}
# 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`)
```env theme={null}
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`)
```env theme={null}
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!** 🚀
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)
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:
```bash theme={null}
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
2. **Create a new organization**
3. **Create a new project**
* Choose a name for your project
* **Important:** Save the database password - you'll need it later
4. **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)
5. **Add to `apps/server/.env`:**
```env theme={null}
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`:**
```env theme={null}
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:**
```bash theme={null}
openssl rand -hex 16
```
2. **Add to `apps/server/.env`:**
```env theme={null}
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](https://console.cloud.google.com)**
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`:**
```env theme={null}
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](https://resend.com)** and sign up
2. **Create an API Key:**
* Go to API Keys section
* Click "Create API Key"
* Copy the key (starts with `re_`)
3. **Add to `apps/server/.env`:**
```env theme={null}
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](https://stripe.com)** and login
2. **Enable Test Mode** (toggle in top right)
