@cyguin/waitlist

Drop-in email waitlist with position tracking and optional referral loop for Next.js apps.

Install

npm install @cyguin/waitlist

Quick start

1. Configure the adapter

// lib/waitlist.ts
import { createSQLiteAdapter } from "@cyguin/waitlist/adapters/sqlite";

export const waitlistAdapter = createSQLiteAdapter();

2. Add the API route

// app/api/waitlist/[...cyguin]/route.ts
import { NextRequest, NextResponse } from "next/server";
import { createWaitlistHandler } from "@cyguin/waitlist/next";
import { waitlistAdapter } from "@/lib/waitlist";

const handler = createWaitlistHandler({ adapter: waitlistAdapter });

export async function GET(req: NextRequest) {
  return handler(req);
}

export async function POST(req: NextRequest) {
  return handler(req);
}

3. Drop in the component

// app/page.tsx
import { WaitlistForm } from "@cyguin/waitlist";

export default function Home() {
  return (
    <main>
      <h1>Join the waitlist</h1>
      <WaitlistForm placeholder="Enter your email" buttonText="Join waitlist" />
    </main>
  );
}

API

POST /api/waitlist

Join the waitlist.

Request:

{
  "email": "user@example.com",
  "referred_by": "TOKEN" // optional
}

Response 201:

{
  "id": "abc123",
  "email": "user@example.com",
  "position": 42,
  "referral_token": "abc123"
}

Response 409 — email already registered:

{ "error": "already_registered" }

GET /api/waitlist?email=xxx

Get your position on the waitlist.

Response 200:

{
  "id": "abc123",
  "email": "user@example.com",
  "position": 42,
  "referral_token": "abc123",
  "joined_at": 1712000000000
}

Response 404 — not found:

{ "error": "not_found" }

Referral system

When a user joins via ?ref=TOKEN, their entry records who referred them. Position is never adjusted based on referral count — referrals are informational only.

1. On POST, a referral_token (the entry's id) is returned.
2. Share links like https://yoursite.com/?ref=TOKEN.
3. New joins with ?ref=TOKEN store the referrer's id.

<WaitlistForm /> Props

Prop	Type	Default	Description
className	string	''	CSS class for the form container
placeholder	string	'Enter your email'	Input placeholder text
buttonText	string	'Join waitlist'	Button label
redirectTo	string	—	If provided, redirects here after success with ?ref=TOKEN
theme	'light' | 'dark'	'dark'	Visual theme. Pass 'light' to opt into the light theme.
onSuccess	(data: JoinResponse) => void	—	Callback on successful join
onError	(error: string) => void	—	Callback on error

Theming

All styling defaults to the cyguin dark theme and uses --cyguin-* CSS custom properties. Default tokens:

--cyguin-bg: #0a0d17 --cyguin-bg-subtle: #101521 --cyguin-border: #252b3a
  --cyguin-border-focus: #f5a800 --cyguin-fg: #f1f3f6 --cyguin-fg-muted: #888888
  --cyguin-accent: #f5a800 --cyguin-accent-dark: #c47f00
  --cyguin-accent-fg: #0a0a0a --cyguin-radius: 6px --cyguin-shadow: 0 1px 4px
  rgba(0, 0, 0, 0.08);

Apply a light theme with the theme prop:

<WaitlistForm theme="light" />

Exports

Export	Description
@cyguin/waitlist	Main package entry — types, adapters, handler
@cyguin/waitlist/next	Next.js route handler for API route
@cyguin/waitlist/react	WaitlistForm component
@cyguin/waitlist/adapters/sqlite	SQLite adapter (better-sqlite3)
@cyguin/waitlist/adapters/postgres	Postgres adapter (postgres.js)