Waitlist System | Bootspring Docs

The Waitlist workflow helps you build anticipation before launch by capturing interested users, implementing referral mechanics, and maintaining engagement through strategic communication.

Overview#

Property	Value
Components	5 (Signup, Referral, Dashboard, Emails, Analytics)
Tier	Free
Typical Duration	3-5 days to build
Best For	Pre-launch signups, beta access, product launches

Outcomes#

A successful waitlist system delivers:

Email capture form with validation
Unique referral links for viral growth
Position tracking to incentivize sharing
Automated email sequences
Analytics dashboard to track growth

System Architecture#

                    ┌─────────────────┐
                    │  Landing Page   │
                    └────────┬────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────┐
│                  Waitlist API                    │
├─────────────────────────────────────────────────┤
│  POST /api/waitlist                             │
│  - Validate email                               │
│  - Generate referral code                       │
│  - Calculate position                           │
│  - Send welcome email                           │
│  - Track referral attribution                   │
└─────────────────────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
              ▼                             ▼
       ┌────────────┐               ┌─────────────┐
       │  Database  │               │   Email     │
       │  (Waitlist │               │   Service   │
       │   entries) │               │  (Resend)   │
       └────────────┘               └─────────────┘

Database Schema#

// prisma/schema.prisma

model WaitlistEntry {
  id            String    @id @default(cuid())
  email         String    @unique
  referralCode  String    @unique
  referredBy    String?   // referralCode of referrer
  position      Int
  referralCount Int       @default(0)
  status        WaitlistStatus @default(PENDING)

  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt

  @@index([referralCode])
  @@index([referredBy])
}

enum WaitlistStatus {
  PENDING
  INVITED
  CONVERTED
  UNSUBSCRIBED
}

API Implementation#

// app/api/waitlist/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prisma } from '@/lib/prisma';
import { nanoid } from 'nanoid';
import { sendWelcomeEmail } from '@/lib/email';
import { z } from 'zod';

const signupSchema = z.object({
  email: z.string().email(),
  referralCode: z.string().optional(),
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { email, referralCode } = signupSchema.parse(body);

    // Check if email already exists
    const existing = await prisma.waitlistEntry.findUnique({
      where: { email },
    });

    if (existing) {
      return NextResponse.json({
        success: true,
        position: existing.position,
        referralCode: existing.referralCode,
        message: "You're already on the list!",
      });
    }

    // Get current position
    const count = await prisma.waitlistEntry.count();
    const position = count + 1;

    // Generate unique referral code
    const newReferralCode = nanoid(8);

    // Create waitlist entry
    const entry = await prisma.waitlistEntry.create({
      data: {
        email,
        referralCode: newReferralCode,
        referredBy: referralCode || null,
        position,
      },
    });

    // Update referrer's count if applicable
    if (referralCode) {
      await prisma.waitlistEntry.updateMany({
        where: { referralCode },
        data: { referralCount: { increment: 1 } },
      });
    }

    // Send welcome email
    await sendWelcomeEmail({
      email,
      position,
      referralCode: newReferralCode,
    });

    return NextResponse.json({
      success: true,
      position,
      referralCode: newReferralCode,
      message: 'Welcome to the waitlist!',
    });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Invalid email address' },
        { status: 400 }
      );
    }
    console.error('Waitlist signup error:', error);
    return NextResponse.json(
      { error: 'Failed to join waitlist' },
      { status: 500 }
    );
  }
}

Position Check Endpoint#

// app/api/waitlist/position/route.ts
export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const email = searchParams.get('email');

  if (!email) {
    return NextResponse.json(
      { error: 'Email required' },
      { status: 400 }
    );
  }

  const entry = await prisma.waitlistEntry.findUnique({
    where: { email },
  });

  if (!entry) {
    return NextResponse.json(
      { error: 'Not found' },
      { status: 404 }
    );
  }

  // Calculate effective position (original - referrals)
  const effectivePosition = Math.max(
    1,
    entry.position - (entry.referralCount * 10) // Each referral moves up 10 spots
  );

  return NextResponse.json({
    position: effectivePosition,
    originalPosition: entry.position,
    referralCount: entry.referralCount,
    referralCode: entry.referralCode,
  });
}

Frontend Components#

Waitlist Form#

// components/marketing/WaitlistForm.tsx
'use client';

import { useState } from 'react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { useSearchParams } from 'next/navigation';

interface WaitlistResult {
  position: number;
  referralCode: string;
}

export function WaitlistForm() {
  const searchParams = useSearchParams();
  const referralCode = searchParams.get('ref');

  const [email, setEmail] = useState('');
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<WaitlistResult | null>(null);
  const [error, setError] = useState('');

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setLoading(true);
    setError('');

    try {
      const res = await fetch('/api/waitlist', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, referralCode }),
      });

      const data = await res.json();

      if (!res.ok) {
        throw new Error(data.error || 'Failed to join');
      }

      setResult({
        position: data.position,
        referralCode: data.referralCode,
      });
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Something went wrong');
    } finally {
      setLoading(false);
    }
  }

  if (result) {
    return <WaitlistSuccess {...result} />;
  }

  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <div className="flex gap-2">
        <Input
          type="email"
          placeholder="Enter your email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          required
          className="flex-1"
        />
        <Button type="submit" disabled={loading}>
          {loading ? 'Joining...' : 'Join Waitlist'}
        </Button>
      </div>
      {error && (
        <p className="text-sm text-destructive">{error}</p>
      )}
      <p className="text-sm text-muted-foreground">
        Join 2,500+ others waiting for early access
      </p>
    </form>
  );
}

Success State with Referral#

// components/marketing/WaitlistSuccess.tsx
'use client';

import { useState } from 'react';
import { Button } from '@/components/ui/button';
import { CheckCircle, Copy, Twitter, Linkedin } from 'lucide-react';

interface WaitlistSuccessProps {
  position: number;
  referralCode: string;
}

export function WaitlistSuccess({ position, referralCode }: WaitlistSuccessProps) {
  const [copied, setCopied] = useState(false);
  const referralUrl = `${window.location.origin}?ref=${referralCode}`;

  async function copyLink() {
    await navigator.clipboard.writeText(referralUrl);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  }

  const twitterText = encodeURIComponent(
    "I just joined the waitlist for [Product Name]! Join me and get early access:"
  );
  const twitterUrl = `https://twitter.com/intent/tweet?text=${twitterText}&url=${encodeURIComponent(referralUrl)}`;

  const linkedinUrl = `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(referralUrl)}`;

  return (
    <div className="text-center space-y-6 p-8 rounded-lg border bg-card">
      <div className="flex justify-center">
        <CheckCircle className="w-16 h-16 text-green-500" />
      </div>

      <div>
        <h3 className="text-2xl font-bold mb-2">You're on the list!</h3>
        <p className="text-4xl font-bold text-primary">#{position}</p>
        <p className="text-muted-foreground">Your position in line</p>
      </div>

      <div className="space-y-3">
        <p className="font-medium">Move up by referring friends</p>
        <p className="text-sm text-muted-foreground">
          Each referral moves you up 10 spots
        </p>

        <div className="flex gap-2">
          <Input
            value={referralUrl}
            readOnly
            className="text-sm"
          />
          <Button variant="outline" onClick={copyLink}>
            {copied ? <CheckCircle className="w-4 h-4" /> : <Copy className="w-4 h-4" />}
          </Button>
        </div>

        <div className="flex justify-center gap-3 pt-4">
          <Button variant="outline" size="sm" asChild>
            <a href={twitterUrl} target="_blank" rel="noopener noreferrer">
              <Twitter className="w-4 h-4 mr-2" />
              Share on Twitter
            </a>
          </Button>
          <Button variant="outline" size="sm" asChild>
            <a href={linkedinUrl} target="_blank" rel="noopener noreferrer">
              <Linkedin className="w-4 h-4 mr-2" />
              Share on LinkedIn
            </a>
          </Button>
        </div>
      </div>
    </div>
  );
}

Email Sequences#

Welcome Email#

// lib/email/templates/waitlist-welcome.ts
import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

interface WelcomeEmailProps {
  email: string;
  position: number;
  referralCode: string;
}

export async function sendWelcomeEmail({
  email,
  position,
  referralCode,
}: WelcomeEmailProps) {
  const referralUrl = `https://yoursite.com?ref=${referralCode}`;

  await resend.emails.send({
    from: 'Your Product <hello@yoursite.com>',
    to: email,
    subject: "You're on the waitlist! Here's how to skip the line",
    html: `
      <h1>Welcome to the Waitlist!</h1>
      <p>You're #${position} in line for early access.</p>

      <h2>Skip the line</h2>
      <p>For every friend who joins using your link, you'll move up 10 spots:</p>
      <p><a href="${referralUrl}">${referralUrl}</a></p>

      <h2>What's next?</h2>
      <ul>
        <li>We'll notify you when it's your turn</li>
        <li>Early access members get 50% off the first year</li>
        <li>Follow us on Twitter for updates</li>
      </ul>
    `,
  });
}

Email Sequence Strategy#

Day	Email	Purpose
0	Welcome	Confirm signup, share referral link
3	Behind the scenes	Share your story, build connection
7	Social proof	Share testimonials or beta feedback
14	Feature preview	Tease upcoming features
21	Urgency	"Launch is coming soon"
Launch	Access email	Invite to sign up

Analytics Dashboard#

Key Metrics to Track#

// lib/analytics/waitlist.ts
export async function getWaitlistMetrics() {
  const [total, today, referrals, conversionRate] = await Promise.all([
    // Total signups
    prisma.waitlistEntry.count(),

    // Signups today
    prisma.waitlistEntry.count({
      where: {
        createdAt: {
          gte: new Date(new Date().setHours(0, 0, 0, 0)),
        },
      },
    }),

    // Referral stats
    prisma.waitlistEntry.aggregate({
      _sum: { referralCount: true },
      _avg: { referralCount: true },
    }),

    // Conversion rate
    prisma.waitlistEntry.groupBy({
      by: ['status'],
      _count: true,
    }),
  ]);

  const converted = conversionRate.find(
    (r) => r.status === 'CONVERTED'
  )?._count || 0;

  return {
    total,
    today,
    referralTotal: referrals._sum.referralCount || 0,
    referralAverage: referrals._avg.referralCount || 0,
    conversionRate: total > 0 ? (converted / total) * 100 : 0,
  };
}

Admin Dashboard Component#

// app/admin/waitlist/page.tsx
import { getWaitlistMetrics } from '@/lib/analytics/waitlist';

export default async function WaitlistDashboard() {
  const metrics = await getWaitlistMetrics();

  return (
    <div className="grid grid-cols-4 gap-4">
      <MetricCard
        title="Total Signups"
        value={metrics.total.toLocaleString()}
      />
      <MetricCard
        title="Today"
        value={metrics.today.toLocaleString()}
      />
      <MetricCard
        title="Referrals"
        value={metrics.referralTotal.toLocaleString()}
      />
      <MetricCard
        title="Viral Coefficient"
        value={(metrics.referralAverage).toFixed(2)}
      />
    </div>
  );
}

Recommended Agents#

Phase	Agent	Purpose
Design	ui-ux-expert	Form and success state design
Backend	backend-expert	API and database implementation
Email	copywriting-expert	Email sequence copy
Analytics	analytics-expert	Dashboard and tracking

Viral Loop Optimization#

Incentive Ideas#

Incentive	Mechanism
Position jump	Move up X spots per referral
Exclusive access	Top referrers get beta access
Rewards	Swag, discounts, or free months
Milestone badges	Unlock achievements for sharing

Best Practices#

Make sharing easy - One-click share buttons
Show progress - Display position changes in real-time
Create urgency - Limited spots, launch countdown
Reward top referrers - Leaderboard or special perks
Send reminders - Periodic emails about position

Deliverables#

Deliverable	Description
Database schema	WaitlistEntry model with referral tracking
API endpoints	Signup, position check, referral tracking
Frontend components	Form, success state, share buttons
Email templates	Welcome, nurture, launch sequence
Admin dashboard	Metrics and waitlist management

Pre-Launch Checklist - Complete preparation
Landing Page - Where to embed waitlist
Launch Day - Convert waitlist to users
Acquisition Channels - Drive waitlist signups