Plugins Overview
Relevant source files
The following files were used as context for generating this wiki page:- packages/plugins/app-invite/src/index.ts
- packages/plugins/feedback/src/index.ts
- packages/plugins/legal-consent/src/index.ts
- packages/plugins/waitlist/src/index.ts
- packages/cli/src/commands/db/database-explorer-plugin.ts
- packages/adapters/convex/src/generate-schema/generate-schema-builder.ts
- README.md
Better Auth Kit is a collection of plugins, adapters, and libraries designed to extend the functionality of the core Better Auth system. Plugins are the primary mechanism for adding new features, such as user invitations, feedback submission, or waitlist management. They are self-contained modules that can define new API endpoints, extend the database schema, and hook into the authentication lifecycle.
This document provides a technical overview of the plugin architecture within the Better Auth Kit, detailing how plugins are structured, how they integrate with the core system, and examples of available plugins.
Sources: README.md, packages/plugins/app-invite/src/index.ts:140-150, packages/plugins/feedback/src/index.ts:31-39
Plugin Architecture
A plugin in Better Auth Kit is an object that conforms to the BetterAuthPlugin interface. Each plugin is designed to be modular and can be easily added to the main betterAuth configuration. The core components of a plugin typically include an ID, API endpoints, schema definitions, and optional hooks or rate-limiting rules.
Sources: packages/plugins/app-invite/src/index.ts:152, packages/plugins/legal-consent/src/index.ts:211
This diagram illustrates the general structure of a BetterAuthPlugin object.
Key Properties
| Property | Description | Source Files |
|---|---|---|
id | A unique string identifier for the plugin (e.g., "app-invite", "feedback"). | packages/plugins/app-invite/src/index.ts:153 |
endpoints | An object where keys are endpoint names and values are AuthEndpoint definitions created with createAuthEndpoint. These define new API routes. | packages/plugins/feedback/src/index.ts:46-59 |
schema | Defines new database tables or extends existing ones. Each key is a model name, and the value describes its fields. | packages/plugins/app-invite/src/index.ts:981-1007 |
hooks | Allows the plugin to execute logic before or after core authentication events, such as sign-up. | packages/plugins/legal-consent/src/index.ts:213-261 |
rateLimit | An array of configurations to apply rate limiting to the plugin's endpoints. | packages/plugins/app-invite/src/index.ts:968-980 |
$ERROR_CODES | A collection of constant error codes specific to the plugin. | packages/plugins/feedback/src/index.ts:44 |
Schema Integration
Plugins seamlessly extend the application's database schema. The core system aggregates schema definitions from all registered plugins to form a complete data model. The getAuthTables and getDetailedAuthTables functions are responsible for this process, iterating through the plugins array in the BetterAuthOptions and merging their schema properties.
This allows plugins to introduce new tables (e.g., appInvitation, feedback) and add new fields to existing core tables like user.
The diagram below shows how schemas from different plugins are aggregated.
Core Plugins
The repository includes several pre-built plugins that provide common authentication-related features.
App Invite Plugin
This plugin allows existing users to invite new users to the application, either via a personal email invitation or a public, shareable link.
Sources: packages/plugins/app-invite/package.json:3, packages/plugins/app-invite/src/index.ts:140-142
Features
- Create personal (email-based) and public (link-based) invitations.
- Optional email sending for invitations.
- Configurable permissions for creating and canceling invitations.
- Automatic sign-in after a user accepts an invitation and signs up.
- Rate limiting on invitation-related endpoints.
Sources: packages/plugins/app-invite/src/index.ts:27-100
API Endpoints
The plugin exposes several endpoints to manage the invitation lifecycle:
| Endpoint | Method | Description |
|---|---|---|
/invite-user | POST | Creates a new personal or public invitation. Requires an active session. |
/get-app-invitation | GET | Retrieves the details of a pending invitation by its ID. |
/accept-invitation | POST | Allows a new user to accept an invitation and sign up. |
/reject-invitation | POST | Allows a user to reject a personal invitation. |
/cancel-invitation | POST | Allows the inviter to cancel an invitation they created. |
/list-invitations | GET | Lists all invitations issued by the currently authenticated user. |
Sources: packages/plugins/app-invite/src/index.ts:154, packages/plugins/app-invite/src/index.ts:311, packages/plugins/app-invite/src/index.ts:420, packages/plugins/app-invite/src/index.ts:708, packages/plugins/app-invite/src/index.ts:796, packages/plugins/app-invite/src/index.ts:861
Invitation Flow
The following sequence diagram illustrates the process of a user accepting an invitation and signing up.
Feedback Plugin
This plugin provides a simple mechanism for authenticated or anonymous users to submit feedback.
Sources: packages/plugins/feedback/README.md:3, packages/plugins/feedback/src/index.ts:31-39
Features
- Configurable text length (
minLength,maxLength). - Option to require authentication (
requireAuth). - Submission limits per user (
feedbackLimit). - Custom validation logic (
canSubmitFeedback). - Extensible schema to include additional feedback fields.
- A callback hook (
onFeedback) that runs after submission.
Sources: packages/plugins/feedback/src/index.ts:19-29
API Endpoint
POST /feedback/submit: Submits feedback. The body includestextand any additional defined fields. It usessessionMiddlewareto identify the user if they are logged in.
Sources: packages/plugins/feedback/src/index.ts:47-59
Legal Consent Plugin
This plugin enforces legal compliance by requiring users to accept various policies during sign-up. It works by hooking into the sign-up/email flow.
Sources: packages/plugins/legal-consent/README.md:3-5, packages/plugins/legal-consent/src/index.ts:213-216
Features
- Requires acceptance of:
- Terms of Service (
requireTOS) - Privacy Policy (
requirePrivacyPolicy) - Age Verification (
requireAgeVerification) - And more.
- Terms of Service (
- Supports versioning for each policy (e.g.,
TosVersion). - Modifies the
userschema to store consent information.
Sources: packages/plugins/legal-consent/src/index.ts:4-53
Hook-based Implementation
The plugin uses a before hook that targets the /sign-up/email path. When a sign-up request is made, this hook intercepts it to validate that all required consent flags are present in the request body. If a required consent is missing, it throws a BAD_REQUEST error.
This flowchart shows the sign-up process with the legal consent hook.
Waitlist Plugin
This plugin allows you to add a waitlist to your application, capturing user interest before a full launch.
Sources: packages/plugins/waitlist/package.json:3
Features
- Enable or disable the waitlist (
enabled). - Set a maximum number of participants (
maximumWaitlistParticipants). - Define actions when the waitlist ends, either by reaching a capacity or a specific date.
- Extensible schema for capturing additional user information.
Sources: packages/plugins/waitlist/src/index.ts:21-30
API Endpoint
POST /waitlist/add-user: Adds a user to the waitlist. It checks for existing users and enforces the participant limit if configured.
Sources: packages/plugins/waitlist/src/index.ts:41-54
Summary
The plugin system is a cornerstone of the Better Auth Kit, providing a powerful and flexible way to extend core authentication functionality. By defining custom endpoints, extending the database schema, and hooking into the request lifecycle, plugins enable developers to tailor the authentication experience to their specific needs. The provided set of plugins for app invites, feedback, legal consent, and waitlists serves as both a useful feature set and a practical guide for developing new, custom plugins.