Table of Contents

• 🔮 Overview
• 🚀 Getting Started
• ✨ Features
• 🔰 Tech Stack
• 🤗 Contributing
• 🎗 License

[!CAUTION] RefRef is still in alpha, expect bugs and breaking changes.

🔮 Overview

Build powerful referral programs for your products with RefRef's open source referral management platform.

🚀 Getting Started

Quick Start with Docker (Recommended)

Get RefRef running in under a minute:

# Clone the repository
git clone https://github.com/refrefhq/refref.git
cd refref

# Start everything with Docker Compose
docker-compose up

That's it! 🎉 The webapp portal will be available at http://localhost:3000.

Docker Compose automatically handles:

• PostgreSQL database setup
• Database migrations
• Initial data seeding
• Webapp portal configuration

To configure optional services (Google OAuth, email), pass environment variables:

GOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=xxx RESEND_API_KEY=xxx docker-compose up

Local Development Setup

If you prefer running RefRef locally without Docker:

Prerequisites

• Node.js 20+
• pnpm 10.23.0
• PostgreSQL database
• portless (npm install -g portless)

Installation

# Install dependencies
pnpm install

# Set up environment variables
cp apps/webapp/.env.example apps/webapp/.env

# Edit .env and add your database URL and auth secret
# Generate auth secret with: openssl rand -base64 32

# Export DATABASE_URL for database commands
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/refref"

# Push database schema
pnpm -F @refref/coredb db:push

# (Optional) Seed with template data
pnpm -F @refref/coredb db:seed

# Start development server
pnpm dev

Each app gets a stable .localhost URL via portless:

Portless is a global CLI tool (npm install -g portless). The proxy auto-starts when you run pnpm dev. To bypass portless, set PORTLESS=0 pnpm dev.

Environment Variables

Required

• DATABASE_URL - PostgreSQL connection string (e.g., postgresql://user:password@localhost:5432/refref)
• BETTER_AUTH_SECRET - Authentication secret key (generate with openssl rand -base64 32)

Optional

• GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET - For Google OAuth authentication
• RESEND_API_KEY - For sending emails via Resend
• BETTER_AUTH_URL - Authentication URL (defaults to http://refref-webapp.localhost:1355)

Development Commands

# Start development server
pnpm dev

# Build for production
pnpm build

# Run linting
pnpm lint

# Format code
pnpm format

# Type checking
pnpm type:check

# Database commands
pnpm -F @refref/coredb db:push     # Push schema changes
pnpm -F @refref/coredb db:migrate  # Run migrations
pnpm -F @refref/coredb db:studio   # Open Drizzle Studio GUI
pnpm -F @refref/coredb db:seed     # Seed with templates

✨ Features

• Referral Attribution: JS snippet for tracking referrals, enabling accurate attribution of referrals to referrers

• Customizable Rewards: Flexible reward system for different referral programs

• Referrer Portal: UI components for referrers to refer and track rewards

• Partner Portal: Dedicated interface for affiliates

• Personalized Pages: Automatic personalization of referral landing pages

• Nudges: Automated reminders to boost referral engagement

• Fraud Monitoring: Detect and prevent fraudulent referral activity

• Manual Reward Approval: Review and approve rewards manually

• Automatic Reward Approval: Set rules for automatic reward validation

• Manual Reward Dispersal: Control when rewards are sent out

• Automatic Reward Dispersal: Schedule automated reward payments

• Engagement Analytics: Track referral program performance metrics

• Testing Environment: Sandbox for testing referral programs

🔰 Tech Stack

• 💻 Typescript
• 🚀 React
• ☘️ Next.js
• 🎨 TailwindCSS
• 🧑🏼‍🎨 Shadcn
• 🔒 Better-Auth
• 🧘‍♂️ Zod
• 🐞 Vitest
• 🗄️ PostgreSQL
• 📚 Fumadocs
• 💽 Drizzle
• 🌀 Turborepo

🤗 Contributing

Contributions are welcome! Please read the Contributing Guide to get started.

• 💡 Contributing Guide: Learn about our contribution process and coding standards.
• 🐛 Report an Issue: Found a bug? Let us know!
• 💬 Start a Discussion: Have ideas or suggestions? We'd love to hear from you.

🎗 License

Released under AGPLv3.