{"id":16604,"library":"better-auth-lead","title":"Better Auth Lead Plugin","description":"The `better-auth-lead` package is a plugin for the `better-auth` ecosystem, designed to extend its core functionality with lead management capabilities. It facilitates features like newsletter sign-ups, waitlists, and general lead capture by providing a dedicated database table (`leads`) and a robust API. Currently at version 0.4.0, the package is in active development, implying potential API changes in minor versions before reaching a stable 1.0 release. Key differentiators include its seamless integration with `better-auth`'s server and client infrastructure, built-in support for email verification with customizable sending logic, and the ability to define and validate lead metadata using standard schema libraries like Zod or Valibot. This allows developers to quickly add lead generation features with strong type safety and validation.","status":"active","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/marcjulian/better-auth-plugins","tags":["javascript","typescript"],"install":[{"cmd":"npm install better-auth-lead","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-lead","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-lead","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for better-auth and requires it as a peer dependency to function.","package":"better-auth","optional":false}],"imports":[{"note":"This is the server-side plugin function for `createBetterAuth`.","wrong":"const { lead } = require('better-auth-lead');","symbol":"lead","correct":"import { lead } from 'better-auth-lead';"},{"note":"The client-side plugin must be imported from the subpath `better-auth-lead/client`.","wrong":"import { leadClient } from 'better-auth-lead';","symbol":"leadClient","correct":"import { leadClient } from 'better-auth-lead/client';"},{"note":"This is an example type import for lead metadata, typically shared between client and server from a schema definition.","symbol":"LeadMetadata","correct":"import type { LeadMetadata } from 'shared/lead-metadata-schema';"}],"quickstart":{"code":"import { createBetterAuth } from '@better-auth/core';\nimport { lead } from 'better-auth-lead';\n// Assume 'sendEmail' is a function that sends an email\n// e.g., using nodemailer, resend, or a custom service.\nasync function sendEmail({ to, subject, text }: { to: string; subject: string; text: string }) {\n  console.log(`Sending email to ${to} with subject: ${subject}`);\n  console.log(`Body: ${text}`);\n  // In a real application, integrate with an email sending service here.\n  // Example: await resend.emails.send({ to, subject, text });\n}\n\nconst betterAuth = createBetterAuth({\n  plugins: [\n    lead({\n      sendVerificationEmail: async ({ lead, url }) => {\n        const { verificationEmailSentAt } = lead;\n        // Implement basic rate-limiting to prevent sending too many emails\n        if (\n          verificationEmailSentAt &&\n          Date.now() - verificationEmailSentAt.getTime() < 60 * 1000 // 1 minute cooldown\n        ) {\n          console.log(\n            `Skipping verification email for ${lead.email}: recent email already sent.`,\n          );\n          return false;\n        }\n\n        void sendEmail({\n          to: lead.email,\n          subject: 'Please verify your email address',\n          text: `Click the link to verify your email: ${url}`,\n        });\n\n        return true; // Indicate that an email was sent\n      },\n      onEmailVerified: async ({ lead }) => {\n        console.log(`Lead ${lead.email} has been successfully verified!`);\n        // Additional logic after email verification, e.g., update CRM, send welcome email\n      }\n    }),\n  ],\n});\n\n// To use betterAuth, you would typically export it or integrate it into an HTTP server setup.\n// For example, in a Next.js API route or an Express app.\n// console.log('Better Auth with Lead plugin configured.');\n","lang":"typescript","description":"This code snippet demonstrates how to configure the `better-auth-lead` server plugin within `createBetterAuth`, including custom logic for sending verification emails and handling post-verification actions. It includes basic rate-limiting for email sending."},"warnings":[{"fix":"Consult the latest README and changelog for specific updates and migration instructions when upgrading. Pin to exact patch versions if stability is critical.","message":"As a pre-1.0 package (currently 0.4.0), API surfaces and configuration options for `better-auth-lead` are subject to change without strict adherence to semantic versioning. Future minor versions (e.g., 0.5.0) may introduce breaking changes.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure you run `npx auth@latest generate` (or `pnpm dlx auth@latest generate`, `yarn dlx auth@latest generate`, `bun x auth@latest generate`) from your project root after plugin installation and configuration.","message":"The `npx auth@latest generate` command must be run after installing and configuring the `better-auth-lead` plugin on the server-side to create the necessary `leads` database table. Failing to do so will result in runtime errors related to missing database tables.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Enhance your `sendVerificationEmail` function with more comprehensive rate-limiting based on IP, email, or other factors, and consider using dedicated email service providers that offer built-in spam protection.","message":"When implementing the `sendVerificationEmail` callback, it is crucial to include robust rate-limiting and anti-spam measures. The provided example includes a basic 1-minute cooldown, but production applications should implement more sophisticated checks to prevent abuse.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Change `import { leadClient } from 'better-auth-lead';` to `import { leadClient } from 'better-auth-lead/client';` in your client-side setup file.","message":"The client-side plugin `leadClient` must be imported from the specific subpath `better-auth-lead/client`. Attempting to import it directly from the package root (`better-auth-lead`) will lead to bundling issues or runtime errors indicating `leadClient` is undefined.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run your `better-auth` migration command, typically `npx auth@latest generate`, from your project's root directory.","cause":"The required database migration for the `leads` table was not executed after configuring the server-side plugin.","error":"table 'leads' does not exist"},{"fix":"Verify that `plugins: [leadClient()]` is included in your `createAuthClient` call in your client-side authentication setup file.","cause":"The `leadClient` plugin was not correctly initialized and added to the `createAuthClient` configuration on the client-side.","error":"TypeError: Cannot read properties of undefined (reading 'lead')"},{"fix":"Adjust the `metadata` payload on the client to match the expected structure and types defined by the server's validation schema (e.g., Zod schema).","cause":"The `metadata` object submitted via `authClient.lead.subscribe` or `authClient.lead.update` does not conform to the `metadata.validationSchema` defined on the server-side plugin configuration.","error":"400 Bad Request - INVALID_METADATA"}],"ecosystem":"npm"}