Quick Start

Welcome to BetterBoilerplate! This guide will walk you through setting up your full-stack project step by step. What you’ll be setting up:

🌐 Frontend - Next.js web application
🗄️ Backend - Express API server
📝 CMS - Content management system
🔐 Authentication - Google OAuth + email login
💳 Payments - Stripe integration
📧 Email - Resend service
🤖 AI - OpenRouter integration
🗃️ Database - PostgreSQL with Supabase

Expected setup time: 15-30 minutes depending on your familiarity with these services.

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 Clone & Install

Clone the repository:

# Using SSH (recommended)
git clone git@github.com:Humanoidz-ai/ultimate-boilerplate-code.git

# Or using HTTPS
git clone https://github.com/Humanoidz-ai/ultimate-boilerplate-code.git

Navigate to the project:
cd ultimate-cursor-ai-boilerplate
Install dependencies:
bun install

1.2 Environment Files Setup

Create environment files from the provided examples:

cp apps/web/.env.example apps/web/.env
cp apps/cms/.env.example apps/cms/.env
cp apps/server/.env.example apps/server/.env

Important: You’ll fill in these environment variables in the following steps. Don’t worry about the values for now.

Step 2: Database Setup (Supabase)

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

2.1 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

2.2 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

Step 3: Authentication Setup

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

3.1 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

3.2 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

Step 4: Email Service Setup (Resend)

What is Resend? It sends transactional emails like password resets and welcome emails.

4.1 Create Resend Account

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

Step 5: Payment Setup (Stripe)

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

5.1 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_)

5.2 Create a Product

Go to Products → Add Product
Set up your product details:
- Name (e.g., “Pro Subscription”)
- Price (e.g., $9.99/month)
- Currency (USD)
Copy the Price ID (starts with price_)

Add to apps/server/.env:

STRIPE_SECRET_KEY=sk_test_your_secret_key
STRIPE_TEST_PRODUCT=price_your_price_id

5.3 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

Step 6: AI Integration (OpenRouter)

What is OpenRouter? It provides access to multiple AI models through a single API.

6.1 Get OpenRouter API Key

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

Add to apps/server/.env:

OPENROUTER_API_KEY=your_openrouter_api_key

Step 7: CMS Secret Generation

What is the CMS? It’s your content management system for blog posts, pages, etc.

7.1 Generate CMS Secret

Generate a secure secret:
openssl rand -hex 32

Add to apps/cms/.env:

PAYLOAD_SECRET=your_generated_cms_secret

Step 8: Frontend Configuration

Configure the frontend app to connect to your backend services.

8.1 Frontend Environment Variables

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

Step 9: Database Migration

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

9.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 10: Launch Your App! 🚀

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

10.2 Alternative: Individual Services

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

10.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:

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

Getting Help

Documentation: Check the individual service docs
Community: Join our Discord for support
Issues: Report bugs on GitHub

Next Steps

🎉 Congratulations! Your BetterBoilerplate 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

​Prerequisites

​Step 1: Project Setup

​1.1 Clone & Install

​1.2 Environment Files Setup

​Step 2: Database Setup (Supabase)

​2.1 Create Main Database

​2.2 Create CMS Database

​Step 3: Authentication Setup

​3.1 Generate Authentication Secret

​3.2 Google OAuth Setup

​Step 4: Email Service Setup (Resend)

​4.1 Create Resend Account

​Step 5: Payment Setup (Stripe)

​5.1 Basic Stripe Setup

​5.2 Create a Product

​5.3 Webhook Setup (Optional but Recommended)

​Step 6: AI Integration (OpenRouter)

​6.1 Get OpenRouter API Key

​Step 7: CMS Secret Generation

​7.1 Generate CMS Secret

​Step 8: Frontend Configuration

​8.1 Frontend Environment Variables

​Step 9: Database Migration

​9.1 Run Database Setup

​Step 10: Launch Your App! 🚀

​10.1 Start All Services

​10.2 Alternative: Individual Services

​10.3 Access Your Apps

​Environment Variables Summary

​Troubleshooting

​Common Issues

​Getting Help

​Next Steps

Quick Start

Prerequisites

Step 1: Project Setup

1.1 Clone & Install

1.2 Environment Files Setup

Step 2: Database Setup (Supabase)

2.1 Create Main Database

2.2 Create CMS Database

Step 3: Authentication Setup

3.1 Generate Authentication Secret

3.2 Google OAuth Setup

Step 4: Email Service Setup (Resend)

4.1 Create Resend Account

Step 5: Payment Setup (Stripe)

5.1 Basic Stripe Setup

5.2 Create a Product

5.3 Webhook Setup (Optional but Recommended)

Step 6: AI Integration (OpenRouter)

6.1 Get OpenRouter API Key

Step 7: CMS Secret Generation

7.1 Generate CMS Secret

Step 8: Frontend Configuration

8.1 Frontend Environment Variables

Step 9: Database Migration

9.1 Run Database Setup

Step 10: Launch Your App! 🚀

10.1 Start All Services

10.2 Alternative: Individual Services

10.3 Access Your Apps

Environment Variables Summary

Troubleshooting

Common Issues

Getting Help

Next Steps