{"id":16778,"library":"better-auth-waitlist","title":"Better Auth Waitlist Plugin","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/LargatSeif/better-auth-waitlist","tags":["javascript","better-auth","waitlist","plugin","authentication","typescript","admin-approval","validation","esm"],"install":[{"cmd":"npm install better-auth-waitlist","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-waitlist","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-waitlist","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication system that this plugin extends, specified as a peer dependency.","package":"better-auth","optional":false},{"reason":"Used for schema validation, listed as the sole direct dependency.","package":"zod","optional":false}],"imports":[{"note":"This package is ESM-only since v3 and does not support CommonJS `require()` syntax.","wrong":"const { waitlist } = require('better-auth-waitlist');","symbol":"waitlist","correct":"import { waitlist } from 'better-auth-waitlist';"},{"note":"Client-side utility for browser/frontend applications, also ESM-only. Ensure correct subpath import.","wrong":"const { waitlistClient } = require('better-auth-waitlist/client');","symbol":"waitlistClient","correct":"import { waitlistClient } from 'better-auth-waitlist/client';"},{"note":"Use `import type` for type-only imports to improve tree-shaking and prevent accidental runtime dependency.","wrong":"import { WaitlistPluginOptions } from 'better-auth-waitlist';","symbol":"WaitlistPluginOptions","correct":"import type { WaitlistPluginOptions } from 'better-auth-waitlist';"}],"quickstart":{"code":"import { betterAuth } from \"better-auth\";\nimport { waitlist } from \"better-auth-waitlist\";\nimport { createAuthClient } from \"better-auth/react\";\nimport { waitlistClient } from \"better-auth-waitlist/client\";\n\n// Server-side: Initialize Better Auth with the waitlist plugin\nexport const auth = betterAuth({\n  plugins: [\n    waitlist({\n      enabled: true,\n      allowedDomains: [\"@example.com\", \"@company.org\"],\n      maximumWaitlistParticipants: 1000,\n      // Example of adding custom fields and auto-approval logic\n      additionalFields: {\n        department: { type: \"string\", required: true },\n        additionalInfo: { type: \"string\", required: false }\n      },\n      autoApprove: (entry) => entry.email.endsWith('@company.org')\n    })\n  ]\n});\n\n// Client-side: Initialize the Better Auth client with the waitlist client plugin\nexport const authClient = createAuthClient({\n  baseURL: process.env.NEXT_PUBLIC_AUTH_URL ?? '', // Ensure this environment variable is set\n  plugins: [waitlistClient()]\n});\n\nasync function demonstrateWaitlist() {\n  // Important: Run `npx @better-auth/cli migrate` once to create the necessary database tables.\n\n  // Join the waitlist\n  try {\n    const joinResult = await authClient.waitlist.join({\n      email: \"user@example.com\",\n      department: \"Engineering\",\n      name: \"Jane Smith\",\n      additionalInfo: \"Need access to internal tools\"\n    });\n    console.log(\"Joined waitlist:\", joinResult);\n\n    // Check waitlist status\n    const status = await authClient.waitlist.checkStatus({\n      email: \"user@example.com\"\n    });\n    console.log(\"Waitlist status:\", status);\n\n    // Example of admin operations (requires admin role and authenticated client)\n    // const allEntries = await authClient.waitlist.list();\n    // console.log('All waitlist entries (admin-only):', allEntries);\n    // await authClient.waitlist.approve({ id: joinResult.id }); // Assuming joinResult contains an ID\n    // console.log('Entry approved by admin.');\n  } catch (error) {\n    console.error(\"Waitlist operation failed:\", error);\n  }\n}\n\ndemonstrateWaitlist();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"`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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js runtime environment to version 18 or greater to ensure compatibility and access to necessary features.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"After installing and configuring the plugin, execute the database migration command: `npx @better-auth/cli migrate`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Refactor your imports to use ES module syntax: `import { waitlist } from 'better-auth-waitlist';`.","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.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure `waitlistClient()` is included in the `plugins` array when calling `createAuthClient`: `plugins: [waitlistClient()]`.","cause":"The `waitlistClient()` plugin was not correctly added to `createAuthClient`'s `plugins` array, or the `authClient` instance was not properly initialized.","error":"TypeError: Cannot read properties of undefined (reading 'waitlist')"},{"fix":"Run the database migration command from your project root: `npx @better-auth/cli migrate`.","cause":"The required database table for waitlist entries has not been created by the Better Auth migration tool.","error":"SQLITE_ERROR: no such table: waitlist_entries"},{"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.","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).","error":"ReferenceError: process is not defined"}],"ecosystem":"npm","meta_description":null}