Project Philosophy
Relevant source files
The following files were used as context for generating this wiki page:Better Auth Kit is a collection of tools designed to extend the core functionality of the Better Auth library. The project's philosophy is centered around modularity, extensibility, and developer experience. It achieves this by providing a pluggable architecture where features can be added through self-contained packages, including plugins, adapters for different backends, and reusable UI components.
This modular approach allows developers to pick and choose the specific functionalities they need, keeping their applications lean while enabling complex features like legal compliance, user feedback systems, and invite-only sign-ups. The project emphasizes a schema-driven design, where plugins can extend the core database schema, and tooling like the Convex adapter can automatically merge these extensions.
Core Architectural Principles
The project is structured as a monorepo, which facilitates the management of its various components. The core philosophy is to separate concerns into distinct package types, each with a specific role.
Sources: package.json, README.md
Monorepo Structure
The repository is organized into several key directories within the packages folder, reflecting its component-based philosophy.
| Package Type | Directory | Purpose |
|---|---|---|
| Plugins | packages/plugins/* | Self-contained modules that add new features and business logic (e.g., legal consent, feedback). |
| Adapters | packages/adapters/* | Provide compatibility layers for specific database or backend technologies (e.g., Convex). |
| Libraries | packages/libraries/* | Offer shared utilities, such as UI components or testing helpers. |
| CLI | packages/cli | A command-line tool to aid development, such as database management. |
Sources: package.json:20-26
This diagram illustrates the high-level relationship between the core better-auth library and the different types of packages provided by better-auth-kit.
Sources: README.md:13-14, package.json:20-26
Pluggable and Extensible by Design
The primary design principle is a pluggable architecture. Plugins are the main mechanism for extending better-auth. They are designed to be self-contained and highly configurable.
Plugin Anatomy
A typical plugin consists of:
- ID: A unique identifier (e.g.,
legal-consent). - Schema Extensions: Definitions to add new tables or fields to the application's database schema.
- Hooks: Middleware functions that run before or after core authentication events (e.g.,
sign-up). - API Endpoints: New routes that the plugin exposes.
- Configuration Options: A set of parameters to customize the plugin's behavior.
Sources: packages/plugins/legal-consent/src/index.ts:169-191, packages/plugins/feedback/src/index.ts:49-183
The following sequence diagram shows how the legal-consent plugin intercepts a sign-up request to enforce that the Terms of Service are accepted.
Schema-Driven Development
The kit strongly relies on a schema-driven approach. Plugins declare their data requirements, which are then integrated into the main application's schema. This ensures data consistency and makes features transparent.
Dynamic Schema Generation (Convex Adapter)
The Convex adapter exemplifies this philosophy by providing a schema builder that automates the integration of plugin schemas. It reads the existing user-defined schema, parses it, and merges it with the schemas defined by all registered better-auth plugins.
This flow diagram illustrates the schema generation process for the Convex adapter.
The system is designed to be non-destructive. It preserves user-defined tables and fields that are not managed by Better Auth plugins, merging them with the plugin-required fields.
Sources: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:121-133
Focus on Developer Experience
The project provides tools to simplify development and testing.
- UI Library: A dedicated
uipackage, built withshadcn, provides pre-built, dynamic UI components for authentication flows like sign-up and sign-in. This accelerates frontend development.
Sources: packages/libraries/ui/package.json:4-5, packages/libraries/ui/registry.json:6-23 - Testing Utilities: The
@better-auth-kit/testspackage offers helpers to facilitate the testing of custom plugins, ensuring reliability.
Sources: packages/libraries/tests/package.json:2-3 - Command-Line Interface (CLI): The
@better-auth-kit/cliincludes developer tools, most notably a database explorer. Thedbcommand launches a web-based UI to inspect the application's database, which is invaluable for debugging.
Sources: packages/cli/src/commands/db/index.ts:10-16, packages/cli/src/commands/db/index.ts:68-72
Example Plugin: Legal Consent
The legal-consent plugin is a clear embodiment of the project's philosophy. It allows developers to enforce compliance requirements during user sign-up with minimal configuration.
Sources: packages/plugins/legal-consent/README.md:3-5
Configuration and Behavior
The plugin is initialized with a configuration object that specifies which consents are required.
| Option | Type | Description |
|---|---|---|
requireTOS | boolean | If true, the user must accept the Terms of Service. |
requirePrivacyPolicy | boolean | If true, the user must accept the Privacy Policy. |
requireAgeVerification | boolean | If true, the user must verify their age. |
TosVersion | string | If provided, stores this version string instead of true. |
schema | object | Allows customizing the database field names for consent flags. |
Sources: packages/plugins/legal-consent/src/index.ts:4-70
When enabled, the plugin uses a before hook on the sign-up route to check for the required consent flags in the request body. If a required flag is missing, it throws a BAD_REQUEST error. Otherwise, it adds the consent data to what will be saved for the new user.
Sources: packages/plugins/legal-consent/src/index.ts:171-224