Plugin: Waitlist
Relevant source files
The following files were used as context for generating this wiki page:
The Waitlist plugin for Better Auth allows you to add a waitlist to your application. When enabled, it prevents users from signing up directly. Instead, they are added to a waitlist. Users can only sign up once a specific condition is met, such as the waitlist reaching a certain size or a specific date passing.
This plugin provides a configurable way to manage user access during a pre-launch or beta phase. It defines a new database schema for waitlist users, exposes an API endpoint to add users to the waitlist, and includes logic to determine when the waitlist period ends.
Sources: packages/plugins/waitlist/README.md, packages/plugins/waitlist/package.json:3, packages/plugins/waitlist/src/index.ts:20-22
Configuration
The plugin is initialized by calling the waitlist function with an options object. The behavior of the waitlist is controlled through these options.
Sources: packages/plugins/waitlist/src/index.ts:20-31, packages/plugins/waitlist/src/types.ts
WaitlistOptions
The main configuration object for the plugin.
| Option | Type | Description | Default |
|---|---|---|---|
enabled | boolean | Whether the waitlist is enabled. | false |
maximumWaitlistParticipants | number | null | The maximum number of users that can join the waitlist. null for no limit. | null |
schema | InferOptionSchema<typeof schema> | Customizes the database schema, allowing for renaming of fields. | undefined |
waitlistEndConfig | WaitlistEndConfig | Configuration for when the waitlist ends. Required if enabled is true. | undefined |
additionalFields | Record<string, FieldAttribute> | Extends the waitlist schema with additional custom fields. | {} |
disableSignInAndSignUp | boolean | Whether to disable sign-in and sign-up routes while the waitlist is active. | false |
Sources: packages/plugins/waitlist/src/index.ts:20-31, packages/plugins/waitlist/src/types.ts:43-85
WaitlistEndConfig
This configuration determines the condition for ending the waitlist.
event | Description | Additional Properties |
|---|---|---|
max-signups-reached | The waitlist ends when the maximumWaitlistParticipants count is reached. The onWaitlistEnd callback is triggered. | N/A |
date-reached | The waitlist ends after the specified date. The onWaitlistEnd callback is triggered. This may not work in serverless environments. | date: Date |
trigger-only | The waitlist can only be ended by manually calling a trigger function. The onWaitlistEnd callback is triggered upon the call. | N/A |
All configurations require an onWaitlistEnd: () => void callback function.
Sources: packages/plugins/waitlist/src/types.ts:4-40
Database Schema
The plugin introduces a waitlist table to the database to store information about users who have joined. The schema is extensible.
Sources: packages/plugins/waitlist/src/schema.ts, packages/plugins/waitlist/src/index.ts:33-37
ER Diagram
This diagram shows the default schema for the waitlist table.
Schema Fields
| Field | Type | Required | Input | Unique | Default Value | Description |
|---|---|---|---|---|---|---|
id | string | true | false | true | generateId() | A unique identifier for the entry. |
email | string | true | true | true | N/A | The user's email address. |
name | string | true | true | false | N/A | The user's name. |
joinedAt | date | true | false | false | new Date() | The date and time the user joined. |
The schema can be extended with custom fields using the additionalFields option. These fields will be added to the waitlist table and included in the API validation.
Sources: packages/plugins/waitlist/src/schema.ts:3-19, packages/plugins/waitlist/src/index.ts:29-30,35-37
API Endpoints
The plugin exposes an endpoint for adding users to the waitlist.
Add Waitlist User
This endpoint handles the logic for adding a new user to the waitlist.
| Property | Value |
|---|---|
| Path | /waitlist/add-user |
| Method | POST |
| Body | { email, name, ... } |
The request body is dynamically validated using a Zod schema generated from the base fields (email, name) and any additionalFields defined in the configuration.
Sources: packages/plugins/waitlist/src/index.ts:48-60, packages/plugins/waitlist/src/index.ts:153-179
Endpoint Flow
The following diagram illustrates the process of adding a user to the waitlist.
Error Codes
The plugin defines specific error codes for common failure scenarios.
| Code | Description |
|---|---|
MAX_PARTICIPANTS_REACHED | Maximum waitlist participants reached. |
USER_EXISTS | User already exists in the waitlist. |
Sources: packages/plugins/waitlist/src/index.ts:14-17
Summary
The Waitlist plugin is a powerful tool for managing application access before a full launch. It offers flexible configuration for defining when the waitlist period concludes, supports custom data fields for waitlist members, and provides a secure endpoint for users to join. By integrating this plugin, developers can easily implement a gated registration flow controlled by participant count, a set date, or manual triggers.