Refref
๐ Open Source Referral and Affiliate Marketing Platform - Launch your referral program in minutes!
Installation
npx refrefAsk AI about Refref
Powered by Claude ยท Grounded in docs
I know everything about Refref. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Website - Docs - Community - Bug reports
Table of Contents
[!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:
| App | URL |
|---|---|
| Webapp | http://refref-webapp.localhost:1355 |
| WWW | http://refref-www.localhost:1355 |
| API | http://refref-api.localhost:1355 |
| Refer | http://refref-refer.localhost:1355 |
| Acme | http://refref-acme.localhost:1355 |
Portless is a global CLI tool (
npm install -g portless). The proxy auto-starts when you runpnpm dev. To bypass portless, setPORTLESS=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 withopenssl rand -base64 32)
Optional
GOOGLE_CLIENT_ID&GOOGLE_CLIENT_SECRET- For Google OAuth authenticationRESEND_API_KEY- For sending emails via ResendBETTER_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.
