Getting Started
Relevant source files
The following files were used as context for generating this wiki page:Better Auth Kit is a monorepo project that provides a collection of plugins, adapters, libraries, and tools to extend the functionality of Better Auth. The kit is designed to be modular, allowing developers to pick and choose the components they need for their specific authentication and user management requirements.
The project is structured as a workspace, managed by turbo, containing various packages for different purposes, such as a command-line interface (CLI), backend adapters (e.g., for Convex), and feature-specific plugins like legal consent management or application invites. This structure facilitates organized development and independent versioning of each component.
Sources: README.md, package.json:15-22
Project Structure
The repository is a monorepo using bun as the package manager and turbo for managing workspace scripts. The core logic is organized into several directories within the packages/ folder.
Sources: package.json:14-22
This diagram illustrates the monorepo workspace configuration.
Sources: package.json:15-22
Key Directories
| Directory | Description |
|---|---|
packages/plugins | Contains plugins that add specific features to Better Auth, such as legal-consent, app-invite, and feedback. |
packages/adapters | Contains adapters for integrating Better Auth with different backends, like convex. |
packages/libraries | Contains shared libraries, such as ui for UI components and tests for testing utilities. |
packages/cli | The source for the @better-auth-kit/cli tool. |
packages/internal | Contains internal packages used for building and development, like bun-build. |
Sources: package.json:15-22, packages/plugins/app-invite/package.json:2, packages/plugins/legal-consent/package.json:2, packages/plugins/feedback/package.json:2, packages/adapters/convex/convex/README.md, packages/libraries/ui/package.json:2, packages/libraries/tests/package.json:2, packages/cli/package.json:2, packages/internal/utils/package.json:2
Core Components
CLI Tool
The Better Auth Kit includes a command-line interface (@better-auth-kit/cli) to aid development. A key feature is the database explorer.
Database Explorer (db command)
The db command starts a local web server that provides a UI for exploring the application's database, as configured in your auth.ts file. It reads the user's Better Auth configuration, injects a special dbExplorerPlugin, and launches a web server on port 3572. It then automatically opens the database explorer UI in the browser.
Sources: packages/cli/src/commands/db/index.ts:18-28, 49-54
The flow for launching the database explorer is as follows:
The command accepts the following options:
| Option | Description |
|---|---|
--config <config> | Specifies the path to the auth configuration file. Defaults to the first auth.ts file found. |
--dev | Adds http://localhost:3001 to the list of allowed CORS origins for local development of the explorer UI. |
Sources: packages/cli/src/commands/db/index.ts:10-16
Adapters (Convex)
Adapters integrate Better Auth with specific backend frameworks. The Convex adapter, for example, provides tools to automatically generate a schema.ts file based on the core Better Auth tables and any additional schemas defined by plugins.
The generateSchemaBuilderStage function is central to this process. It parses an existing schema.ts file, identifies tables managed by Better Auth, and merges them with schemas from the configured plugins.
Sources: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:17-25
The schema generation process follows these steps:
This diagram shows how the Convex adapter builds the final schema by combining existing definitions with those from Better Auth plugins.
Sources: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:28-124
Plugins (Legal Consent)
Plugins extend Better Auth's core functionality. The legal-consent plugin, for instance, enforces user consent for legal documents like Terms of Service (TOS) and Privacy Policies during sign-up.
It works by:
- Extending the User Schema: It adds new fields to the
usermodel based on its configuration (e.g.,tosAccepted,privacyPolicyAccepted). The type can bebooleanorstringif a version is provided. - Adding a Middleware Hook: It uses a
beforehook on the/sign-up/emailroute to validate that the required consent flags are present in the request body. If a required consent is missing, it throws aBAD_REQUESTerror.
Sources: packages/plugins/legal-consent/src/index.ts:121-158, 191-198, packages/plugins/legal-consent/README.md
Configuration
The legalConsent plugin is configured with an options object.
| Option | Type | Description | Default |
|---|---|---|---|
requireTOS | boolean | If true, requires tosAccepted in sign-up requests. | false |
TosVersion | string | If provided, saves this version string instead of true. | undefined |
requirePrivacyPolicy | boolean | If true, requires privacyPolicyAccepted. | false |
PrivacyPolicyVersion | string | If provided, saves this version string instead of true. | undefined |
requireAgeVerification | boolean | If true, requires ageVerified. | false |
AgeVerificationVersion | string | If provided, saves this version string instead of true. | undefined |
schema | object | Allows customizing the field names in the user model. | { userModelName: "user", ... } |
Sources: packages/plugins/legal-consent/src/index.ts:4-77
The following diagram shows the logic of the before hook for the legal consent plugin.
Conclusion
Getting started with Better Auth Kit involves understanding its modular architecture. You can leverage the CLI for development tasks like database inspection, integrate various backend adapters like Convex for seamless schema management, and enhance functionality by adding plugins like legal-consent. Each part of the kit is designed to work together to provide a comprehensive and customizable authentication solution built on top of Better Auth.
Sources: README.md, packages/cli/README.md, packages/plugins/legal-consent/README.md