Website - Docs - Community - Bug reports
Caution
RefRef is still in alpha, expect bugs and breaking changes.
Build powerful referral programs for your products with RefRef's open source referral management platform.
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 upThat'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 upIf you prefer running RefRef locally without Docker:
- Node.js 20+
- pnpm 10.23.0
- PostgreSQL database
- portless (
npm install -g portless)
# 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 commandsexport 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 devEach 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.
DATABASE_URL- PostgreSQL connection string (e.g.,postgresql://user:password@localhost:5432/refref)BETTER_AUTH_SECRET- Authentication secret key (generate withopenssl rand -base64 32)
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)
# 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 templatesReferral 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
- 💻 Typescript
- 🚀 React
- ☘️ Next.js
- 🎨 TailwindCSS
- 🧑🏼🎨 Shadcn
- 🔒 Better-Auth
- 🧘♂️ Zod
- 🐞 Vitest
- 🗄️ PostgreSQL
- 📚 Fumadocs
- 💽 Drizzle
- 🌀 Turborepo
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.
Released under AGPLv3.