better-auth-waitlist

Better Auth Waitlist Plugin

A production-ready Better Auth plugin that provides a comprehensive waitlist system with admin approval workflows, domain restrictions, and customizable validation.

💡 Inspired by: Better Auth Kit Waitlist Plugin - This implementation follows similar patterns and conventions.

Bundle Size

📦 Lightweight & Optimized

Metric	Size
Minified	~22 kB
Gzipped	~3.5 kB
Dependencies	1 (zod only)
Modules	ESM

💡 Tip: Check the impact on your bundle with Bundle Analyzer or use npm ls to see the dependency tree.

Installation

npm install better-auth-waitlist

or

pnpm add better-auth-waitlist

or

yarn add better-auth-waitlist

Quick Start

1. Add the Plugin to Better Auth

import { betterAuth } from "better-auth";
import { waitlist } from "better-auth-waitlist";

export const auth = betterAuth({
  plugins: [
    waitlist({
      enabled: true,
      allowedDomains: ["@example.com", "@company.org"],
      maximumWaitlistParticipants: 1000,
    }),
  ],
});

2. Run Database Migration

Create the waitlist table:

npx @better-auth/cli migrate

3. Setup Client Plugin

import { createAuthClient } from "better-auth/react";
import { waitlistClient } from "better-auth-waitlist/client";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_AUTH_URL,
  plugins: [waitlistClient()],
});

4. Use in Your Application

// Join the waitlist
const result = await authClient.waitlist.join({
  email: "[e-mail]",
  department: "Engineering",
  name: "Jane Smith",
  additionalInfo: "Need access to internal tools",
});

// Check waitlist status
const status = await authClient.waitlist.checkStatus({
  email: "[e-mail]"
});

// Admin operations (requires admin role)
const entries = await authClient.waitlist.list();
const entry = await authClient.waitlist.findOne({ id: "entry-id" });

// Approve/reject entries (admin only)
await authClient.waitlist.approve({ id: "entry-id" });
await authClient.waitlist.reject({ id: "entry-id" });

Configuration Options

Option	Type	Default	Description
enabled	boolean	false	Enable/disable the waitlist
allowedDomains	string[]	undefined	Restrict to specific email domains
maximumWaitlistParticipants	number	undefined	Set capacity limits
additionalFields	Record<string, FieldAttribute>	{}	Extend schema with custom fields
autoApprove	boolean | function	false	Auto-approve based on criteria
validateEntry	function	undefined	Custom validation hooks
onStatusChange	function	undefined	Status change callbacks
disableSignInAndSignUp	boolean	false	Complete waitlist mode

Additional Options

Option	Type	Default	Description
onJoinRequest	function	undefined	Callback when new requests are submitted
canManageWaitlist	function	undefined	Custom function to check admin permissions
rateLimit	object	undefined	Rate limiting configuration
notifications	object	undefined	Notification settings

API Endpoints

• POST /api/auth/waitlist/join - Join the waitlist
• GET /api/auth/waitlist/list - List waitlist entries (admin only)
• GET /api/auth/waitlist/request/find - Find specific waitlist entry (admin only)
• GET /api/auth/waitlist/request/check-status - Check waitlist status by email
• POST /api/auth/waitlist/request/approve - Approve entry (admin only)
• POST /api/auth/waitlist/request/reject - Reject entry (admin only)

Advanced Usage

Custom Validation

waitlist({
  enabled: true,
  validateEntry: async ({ email, additionalData }) => {
    // Custom business logic
    return email.includes("admin") || additionalData?.priority === "high";
  },
  onStatusChange: async (entry) => {
    // Send notification emails
    console.log(`Entry ${entry.id} status changed to ${entry.status}`);
  },
  onJoinRequest: async ({ request }) => {
    // Handle new join requests
    console.log(`New request from ${request.email}`);
  },
});

Schema Extension

waitlist({
  enabled: true,
  additionalFields: {
    department: {
      type: "string",
      required: true,
    },
    reason: {
      type: "string",
      required: false,
    },
  },
});

What's New in v3.0.0

🚀 Major Architectural Refactoring

• 90% smaller main plugin file (from ~500 to ~200 lines)
• Optimized bundle size - lightweight at ~22kB minified (~3.5kB gzipped)
• Modular architecture with separated concerns
• Self-contained - removed external dependencies (stoker removed)
• Better TypeScript support with improved inference
• Enhanced error handling with dedicated error codes
• Improved testing with isolated components
• Tree-shakable ESM modules for better bundling

New File Structure

• error-codes.ts - HTTP status codes and error handling
• client.ts - Simplified client plugin
• schema.ts - Enhanced Zod schemas
• types.ts - TypeScript type definitions

This refactor makes the plugin much more maintainable and follows established Better Auth plugin conventions.

Requirements

• Better Auth ^1.3.4
• Node.js 18+
• TypeScript 5.0+

License

MIT

Acknowledgments

This plugin was inspired by the Better Auth Kit Waitlist Plugin and follows similar architectural patterns and conventions established by the Better Auth ecosystem.

Contributing

Issues and pull requests are welcome! Please ensure your contributions follow the existing code style and include appropriate tests.