Better Auth Waitlist Plugin

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to use `require()` to import `better-auth-waitlist` or its subpaths in an environment configured for ES Modules, or when the package itself is ESM-only.
  fix Refactor your imports to use ES module syntax: `import { waitlist } from 'better-auth-waitlist';`.

• TypeError: Cannot read properties of undefined (reading 'waitlist')

  cause The `waitlistClient()` plugin was not correctly added to `createAuthClient`'s `plugins` array, or the `authClient` instance was not properly initialized.
  fix Ensure `waitlistClient()` is included in the `plugins` array when calling `createAuthClient`: `plugins: [waitlistClient()]`.

• SQLITE_ERROR: no such table: waitlist_entries

  cause The required database table for waitlist entries has not been created by the Better Auth migration tool.
  fix Run the database migration command from your project root: `npx @better-auth/cli migrate`.

• ReferenceError: process is not defined

  cause Accessing `process.env` directly in a client-side environment without proper polyfilling or environment variable injection by a build tool (e.g., in a vanilla browser environment).
  fix Ensure that environment variables like `NEXT_PUBLIC_AUTH_URL` are correctly accessed and bundled for client-side code by your framework's build process, often requiring specific syntax like `import.meta.env` or framework-specific conventions.

Warnings

• breaking `better-auth-waitlist` v3 and newer are pure ES Modules (ESM) and no longer support CommonJS `require()` syntax. This change affects how the package is imported and used in Node.js environments.
  Fix: Migrate your project to use ES module import syntax (`import ... from '...'`) for all imports from this package. If your project is a Node.js application, ensure your `package.json` includes `'type': 'module'` or use `.mjs` file extensions.
• breaking The `better-auth-waitlist` package now requires Node.js version 18 or higher. This update aligns with modern JavaScript features and dependency requirements, and older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js runtime environment to version 18 or greater to ensure compatibility and access to necessary features.
• gotcha Installing and configuring the waitlist plugin requires a database migration to create the necessary waitlist_entries table and any related schemas. Without this migration, the plugin will not function correctly and will likely throw database errors.
  Fix: After installing and configuring the plugin, execute the database migration command: `npx @better-auth/cli migrate`.
• gotcha Accessing administrative waitlist operations (e.g., `list`, `findOne`, `approve`, `reject`) through the `authClient` requires the authenticated user to possess appropriate admin roles within your Better Auth setup. Without these roles, access will be denied.
  Fix: Ensure your Better Auth implementation correctly assigns and validates admin roles for users managing the waitlist. You may need to implement a custom `canManageWaitlist` function in the plugin configuration for specific authorization logic.
• gotcha The `createAuthClient` function on the client-side requires a `baseURL` to specify the endpoint of your Better Auth backend API. In typical web frameworks, this is often provided via environment variables.
  Fix: Set the `NEXT_PUBLIC_AUTH_URL` environment variable (or the equivalent for your framework, such as `VITE_AUTH_URL` or `REACT_APP_AUTH_URL`) to the correct URL of your Better Auth API endpoint.

Install

• npm install better-auth-waitlist npm
• yarn add better-auth-waitlist yarn
• pnpm add better-auth-waitlist pnpm

Imports

• waitlist
  wrong:

  const { waitlist } = require('better-auth-waitlist');

  correct:

  import { waitlist } from 'better-auth-waitlist';

  This package is ESM-only since v3 and does not support CommonJS `require()` syntax.
• waitlistClient
  wrong:

  const { waitlistClient } = require('better-auth-waitlist/client');

  correct:

  import { waitlistClient } from 'better-auth-waitlist/client';

  Client-side utility for browser/frontend applications, also ESM-only. Ensure correct subpath import.
• WaitlistPluginOptions
  wrong:

  import { WaitlistPluginOptions } from 'better-auth-waitlist';

  correct:

  import type { WaitlistPluginOptions } from 'better-auth-waitlist';

  Use `import type` for type-only imports to improve tree-shaking and prevent accidental runtime dependency.

Quickstart

This quickstart demonstrates how to configure the `better-auth-waitlist` plugin for both server-side Better Auth initialization and client-side application integration. It includes examples of defining custom fields and auto-approval logic for the server plugin, setting up the client with a base URL, and performing common waitlist operations such as joining and checking entry status. It also highlights the crucial step of running database migrations.

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

// Server-side: Initialize Better Auth with the waitlist plugin
export const auth = betterAuth({
  plugins: [
    waitlist({
      enabled: true,
      allowedDomains: ["@example.com", "@company.org"],
      maximumWaitlistParticipants: 1000,
      // Example of adding custom fields and auto-approval logic
      additionalFields: {
        department: { type: "string", required: true },
        additionalInfo: { type: "string", required: false }
      },
      autoApprove: (entry) => entry.email.endsWith('@company.org')
    })
  ]
});

// Client-side: Initialize the Better Auth client with the waitlist client plugin
export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_AUTH_URL ?? '', // Ensure this environment variable is set
  plugins: [waitlistClient()]
});

async function demonstrateWaitlist() {
  // Important: Run `npx @better-auth/cli migrate` once to create the necessary database tables.

  // Join the waitlist
  try {
    const joinResult = await authClient.waitlist.join({
      email: "user@example.com",
      department: "Engineering",
      name: "Jane Smith",
      additionalInfo: "Need access to internal tools"
    });
    console.log("Joined waitlist:", joinResult);

    // Check waitlist status
    const status = await authClient.waitlist.checkStatus({
      email: "user@example.com"
    });
    console.log("Waitlist status:", status);

    // Example of admin operations (requires admin role and authenticated client)
    // const allEntries = await authClient.waitlist.list();
    // console.log('All waitlist entries (admin-only):', allEntries);
    // await authClient.waitlist.approve({ id: joinResult.id }); // Assuming joinResult contains an ID
    // console.log('Entry approved by admin.');
  } catch (error) {
    console.error("Waitlist operation failed:", error);
  }
}

demonstrateWaitlist();