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.

For detailed explanations of all environment variables, see the Environment Variables Guide.

Database Configuration

Navigate to the database package:

cd packages/db

Create the environment file:

cp .env.example .env

Edit packages/db/.env with your database connection string:

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

See the Environment Variables Guide for detailed DATABASE_URL format and setup instructions.

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. You'll need to set:

• DATABASE_URL (same as packages/db/.env)
• BETTER_AUTH_SECRET - See Environment Variables Guide for generation instructions
• BETTER_AUTH_URL=http://localhost:4000
• ALLOWED_ORIGINS=http://localhost:3000
• Other optional variables for email and rate limiting (see Environment Variables Guide for details)

Frontend Web Configuration

Navigate to the web app:

cd ../web

Create the environment file:

cp .env.example .env.local

Edit apps/web/.env.local. You'll need to set:

• DATABASE_URL (same as packages/db/.env)
• BETTER_AUTH_SECRET - Must be identical to apps/api/.env.local (see Environment Variables Guide)
• BETTER_AUTH_URL=http://localhost:3000
• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (OAuth credentials)
• Other optional variables for email and rate limiting (see Environment Variables Guide for details)

For complete setup instructions and all available variables, see the Environment Variables Guide.

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 each application. For the complete list of URLs and ports, see Application Ports.

Quick checks:

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

Custom Ports

By default, applications run on specific ports (see Application Ports). To run an application on a different port:

# Web app on custom port
PORT=3010 pnpm dev --filter=web

# API on custom port
PORT=4010 pnpm dev --filter=api

This is useful when a default port is already in use. See Troubleshooting: Port Already in Use for more solutions.