First Steps

Let's get your build-elevate project running. This guide will walk you through configuration and your first successful run.

Overview

Before starting the development servers, you need to:

1. Configure environment variables for all apps
2. Set up the PostgreSQL database
3. Run database migrations
4. Start the development servers

Step 1: Configure Environment Variables

build-elevate uses environment variables to configure database connections, authentication secrets, and API keys. You need to set up three .env files.

Database Configuration

Navigate to the database package:

cd packages/db

Create the environment file:

cp .env.example .env

Edit packages/db/.env:

# Database connection string
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/build_elevate?schema=public"

# For Prisma Migrate (development only)
# Use a separate shadow database for migrations
# DATABASE_URL="postgresql://postgres:postgres@localhost:5432/build_elevate_shadow?schema=public"

Database URL Format

postgresql://[username]:[password]@[host]:[port]/[database]?schema=public

Backend API Configuration

Navigate to the API directory:

cd ../../apps/api

Create the environment file:

cp .env.example .env.local

Edit apps/api/.env.local:

# Server Configuration
NODE_ENV=development
PORT=4000

# Database (same as packages/db/.env)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/build_elevate?schema=public"

# CORS Configuration
ALLOWED_ORIGINS=http://localhost:3000

# Better Auth
BETTER_AUTH_SECRET="your-secret-key-here-min-32-chars"
BETTER_AUTH_URL=http://localhost:4000

# Upstash Redis (for rate limiting)
UPSTASH_REDIS_REST_URL=https://YOUR_REDIS_ENDPOINT.upstash.io
UPSTASH_REDIS_REST_TOKEN=AXXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate a Secret Key

Generate a secure secret for Better Auth:

# Option 1: Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Option 2: Using OpenSSL
openssl rand -hex 32

# Option 3: Online generator
# Visit: https://generate-secret.vercel.app/32

Copy the generated string and paste it as BETTER_AUTH_SECRET.

Frontend Web Configuration

Navigate to the web app:

cd ../web

Create the environment file:

cp .env.example .env.local

Edit apps/web/.env.local:

# Google OAuth (Get from https://console.cloud.google.com/apis/credentials)
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx

# Better Auth
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=your-betterauth-secret

# Database connection string
DATABASE_URL="postgresql://postgres:password@postgres:5432/build-elevate-app"

# Other
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Email service
RESEND_TOKEN=re_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
RESEND_EMAIL_FROM=delivered@resend.dev

# Upstash Redis (for rate limiting)
UPSTASH_REDIS_REST_URL=https://YOUR_REDIS_ENDPOINT.upstash.io
UPSTASH_REDIS_REST_TOKEN=AXXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Node environment
NODE_ENV=development

Step 2: Set Up the Database

Now that environment variables are configured, let's set up the database.

Create the Database

We recommend Supabase for a managed PostgreSQL database. Set up a free project and get the connection string.

Run Migrations

Navigate back to the root directory and run migrations:

cd ../..  # Back to project root

# Run Prisma migrations
npm run db:migrate

This command will:

1. Apply all database migrations
2. Generate Prisma Client
3. Create all necessary tables

You should see output like:

✔ Generated Prisma Client
✔ Applied 1 migration(s)

Step 3: Start Development Servers

Now for the exciting part - let's start your project!

Start All Applications

From the root directory, run:

pnpm dev

This single command starts:

• Web App (Next.js) on http://localhost:3000
• API Server (Express) on http://localhost:4000
• Email Preview (React Email) on http://localhost:3002
• Prisma Studio (Database UI) on http://localhost:5555

Verify Everything Works

Open your browser and check:

1. Frontend: http://localhost:3000

   • You should see the homepage

2. API Health: http://localhost:4000/health

   • Should return: {"status":"ok","timestamp":"..."}

3. Email Preview: http://localhost:3002

   • View all email templates

4. Prisma Studio: http://localhost:5555

   • Browse your database tables

Step 4: Test Authentication

Let's test the authentication system:

1. Navigate to the sign-up page: http://localhost:3000/sign-up

2. Create an account:

   • Enter your email
   • Choose a password (min 8 characters)
   • Click "Sign Up"

3. Check your email:

   • An email will be sent to the address you provided
   • Click the verification link in the email

4. Sign in: You'll be redirected to the dashboard

5. Check the database: Open Prisma Studio to see your user

Development Workflow

Now that everything is running, here are the essential commands you'll use daily:

Common Commands

npm run dev

Individual Applications

If you want to run apps individually:

# Web app only
pnpm dev --filter=web

# API only
pnpm dev --filter=api

# Email preview only
pnpm dev --filter=email

# Multiple specific apps
pnpm dev --filter=web --filter=api