Development Setup - ThriveSend B2B2G

Development Setup - ThriveSend B2B2G

Last Updated: October 20, 2025

---

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Software	Minimum Version	Recommended	Purpose
Node.js	20.x LTS	20.11+	JavaScript runtime
pnpm	8.x	Latest	Package manager
PostgreSQL	16.x	16.1+	Database
Git	2.x	Latest	Version control

Optional Tools

• Prisma Studio: GUI for database (included with Prisma)
• VS Code: Recommended IDE with extensions
• Docker: For containerized PostgreSQL (optional)

---

Installation Steps

1. Clone the Repository

# Clone via SSH (recommended)
git clone git@github.com:gedeza/thrive-send-b2b2g.git

# Or via HTTPS
git clone https://github.com/gedeza/thrive-send-b2b2g.git

# Navigate to project
cd thrive-send-b2b2g

2. Install pnpm (if not installed)

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version
# Should output: 8.x or higher

3. Install Dependencies

# Install all project dependencies
pnpm install

# This will install:
# - Next.js 15.5.4
# - TypeScript 5.x
# - Prisma 6.x
# - Clerk Auth
# - Radix UI + shadcn/ui
# - And 100+ other dependencies

Screenshot Placeholder:

../../assets/images/screenshots/dev-setup-pnpm-install.png

4. Set Up PostgreSQL Database

Option A: Local PostgreSQL

# Install PostgreSQL 16 (Ubuntu/Debian)
sudo apt update
sudo apt install postgresql-16 postgresql-contrib-16

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql

-- In PostgreSQL shell:
CREATE DATABASE thrivesend_dev;
CREATE USER thrivesend WITH PASSWORD 'devpassword';
GRANT ALL PRIVILEGES ON DATABASE thrivesend_dev TO thrivesend;
\q

Option B: Docker PostgreSQL

# Run PostgreSQL in Docker
docker run --name thrivesend-postgres \
  -e POSTGRES_DB=thrivesend_dev \
  -e POSTGRES_USER=thrivesend \
  -e POSTGRES_PASSWORD=devpassword \
  -p 5432:5432 \
  -d postgres:16

5. Configure Environment Variables

Create .env.local file in the project root:

# Copy example environment file
cp .env.example .env.local

Edit .env.local with your values:

# Database
DATABASE_URL="postgresql://thrivesend:devpassword@localhost:5432/thrivesend_dev"

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_your-key-here"
CLERK_SECRET_KEY="sk_test_your-key-here"

# Clerk URLs
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding/organization

# Resend Email (optional for local dev)
RESEND_API_KEY="re_your-key-here"
RESEND_FROM_EMAIL="noreply@yourdomain.com"

# Redis (optional for local dev)
REDIS_URL="redis://localhost:6379"

# Sentry (optional for local dev)
SENTRY_DSN="your-sentry-dsn"

# Application
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NODE_ENV="development"

Screenshot Placeholder:

../../assets/images/screenshots/dev-setup-env-config.png

6. Set Up Clerk Authentication

1. Go to https://clerk.com and create an account
2. Create a new application
3. Select “Next.js” as your framework
4. Copy the API keys to your .env.local
5. Configure organization settings:
   • Enable “Organizations” feature
   • Set organization roles

Screenshot Placeholder:

../../assets/images/screenshots/dev-setup-clerk-dashboard.png

7. Initialize Database with Prisma

# Generate Prisma Client
npx prisma generate

# Run database migrations
npx prisma migrate dev

# You'll see output like:
# ✔ Generated Prisma Client
# ✔ Applied 1 migration
# Database schema is up to date!

# Seed the database with sample data
npx prisma db seed

# This creates:
# - Sample organizations
# - Test users
# - Sample clients (government and business)
# - Test campaigns

Screenshot Placeholder:

../../assets/images/screenshots/dev-setup-prisma-migrate.png

8. Verify Installation

# Run the development server
pnpm dev

# You should see:
# ▲ Next.js 15.5.4
# - Local:        http://localhost:3000
# - Environments: .env.local
# ✓ Ready in 2.5s

Open http://localhost:3000 in your browser.

Screenshot Placeholder:

../../assets/images/screenshots/dev-setup-app-running.png

---

VS Code Setup (Recommended)

Install Recommended Extensions

Create .vscode/extensions.json:

{
  "recommendations": [
    "prisma.prisma",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-playwright.playwright",
    "github.copilot"
  ]
}

Configure VS Code Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

---

Verify Development Environment

Run the following commands to verify everything is set up correctly:

# 1. Check Node.js version
node --version
# Expected: v20.x.x

# 2. Check pnpm version
pnpm --version
# Expected: 8.x.x

# 3. Check PostgreSQL connection
npx prisma db execute --stdin <<< "SELECT 1;"
# Expected: Query executed successfully

# 4. Check Prisma Client
npx prisma generate
# Expected: ✔ Generated Prisma Client

# 5. Run linter
pnpm lint
# Expected: No errors (or only warnings)

# 6. Run tests
pnpm test
# Expected: Tests pass (may have some skipped)

# 7. Build the project
pnpm build
# Expected: ✓ Compiled successfully

---

Common Setup Issues

Issue: Port 3000 Already in Use

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
pnpm dev -- -p 3001

Issue: Prisma Client Not Generated

# Delete node_modules and reinstall
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

# Generate Prisma Client
npx prisma generate

Issue: Database Connection Failed

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -h localhost -U thrivesend -d thrivesend_dev

# Check DATABASE_URL in .env.local
echo $DATABASE_URL

Issue: Clerk Authentication Not Working

1. Verify API keys in .env.local
2. Check Clerk dashboard for application status
3. Ensure organization feature is enabled
4. Clear browser cookies and retry

---

Next Steps

Now that your development environment is set up:

1. Read Project Structure to understand the codebase
2. Explore System Design for architecture overview

---

Getting Help

• Setup Issues: Check Common Setup Issues above
• Clerk Issues: Clerk Documentation
• Prisma Issues: Prisma Documentation
• Next.js Issues: Next.js Documentation

---

Last Updated: October 20, 2025