Registry / auth-security / better-auth-waitlist

better-auth-waitlist

JSON →
library3.0.1jsnpmunverified

The `better-auth-waitlist` package, currently at version 3.0.1, is a lightweight and production-ready plugin designed to integrate comprehensive waitlist management into the Better Auth authentication system. It offers features such as administrative approval workflows, restrictions based on email domains, and highly customizable validation for waitlist entries. The package is optimized for minimal bundle size, weighing approximately ~22 kB minified and ~3.5 kB gzipped, and lists `zod` as its only direct runtime dependency. Shipping exclusively as an ES module (ESM), it mandates a Node.js environment of version 18 or higher. Its primary differentiators include deep integration with Better Auth, flexible configuration options for various waitlist use cases (e.g., capacity limits, auto-approval, custom data fields), and client-side utilities for seamless application integration, supporting operations like joining, status checks, and admin-only actions such as listing, finding, approving, and rejecting entries.

npm install better-auth-waitlist
INSTALL
IMPORT
SIG · BETTER-AUTH-WAITLI
B
better-auth-waitlist
auth-securityjavascriptv3.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

waitlist
import { waitlist } from 'better-auth-waitlist';
const { waitlist } = require('better-auth-waitlist');
This package is ESM-only since v3 and does not support CommonJS `require()` syntax.
waitlistClient
import { waitlistClient } from 'better-auth-waitlist/client';
const { waitlistClient } = require('better-auth-waitlist/client');
Client-side utility for browser/frontend applications, also ESM-only. Ensure correct subpath import.
WaitlistPluginOptions
import type { WaitlistPluginOptions } from 'better-auth-waitlist';
import { WaitlistPluginOptions } from 'better-auth-waitlist';
Use `import type` for type-only imports to improve tree-shaking and prevent accidental runtime dependency.

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();
Debug
Known issues
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.
affects: >=3.0.0
breakingThe `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.
affects: >=3.0.0
gotchaInstalling 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`.
affects: >=1.0.0
gotchaAccessing 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.
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
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')
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
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
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.
Upgrade
Version history
3.0.1latest on npm
Audit
Dependencies
better-authrequiredCore authentication system that this plugin extends, specified as a peer dependency.
zodrequiredUsed for schema validation, listed as the sole direct dependency.
Agent activity
30 hits · last 30 days
node
28
OpenAI (training)
1
Resources