Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• packages/plugins/legal-consent/src/index.ts
• packages/adapters/convex/src/generate-schema/generate-schema-builder.ts
• packages/cli/src/commands/db/index.ts
• packages/plugins/legal-consent/README.md
• packages/cli/package.json
• packages/libraries/ui/package.json

Better Auth Kit is a monorepo project that provides a collection of plugins, adapters, libraries, and command-line tools designed to extend the core functionality of Better Auth. The project is structured as a set of workspaces managed by turbo and bun, allowing for modular development and easy integration of new features.

The primary goal of the kit is to offer pre-built solutions for common authentication-related needs, such as legal compliance, application invites, file storage, and more. It achieves this through a pluggable architecture, where developers can pick and choose the components they need for their specific application.

Sources: README.md:13-15, package.json:19-25

Project Architecture

The repository is organized as a monorepo using workspaces. This structure separates the different types of packages, making the project scalable and maintainable. The main categories are defined in the root package.json.

Sources: package.json:20-25

Workspace Structure

The following diagram illustrates the high-level directory structure of the monorepo.

Sources: package.json:20-25

Package Categories

The core logic is divided into several categories of packages, each with a distinct purpose.

Category	Path	Description
CLI	packages/cli	A command-line interface for development and management tasks.
Plugins	packages/plugins/*	Extendable modules that add specific features to Better Auth.
Libraries	packages/libraries/*	Shared code, such as UI components or testing utilities.
Adapters	packages/adapters/*	Connects Better Auth to specific backend frameworks or databases.
Internal	packages/internal/*	Internal utilities used for building and developing the kit itself.

Sources: package.json:21-25

Core Components

The kit is composed of several key component types that work together to provide a comprehensive authentication solution.

Plugins

Plugins are the primary way to add features to a Better Auth implementation. They can modify database schemas, add API endpoints, and hook into the authentication lifecycle.

Sources: packages/plugins/legal-consent/src/index.ts:1, packages/plugins/feedback/src/index.ts:1

Example: Legal Consent Plugin

The @better-auth-kit/legal-consent plugin ensures an application remains compliant by requiring users to agree to legal terms during sign-up. It can enforce acceptance of:

• Terms of Service
• Privacy Policy
• Age Verification
• Marketing Consent
• Cookie Consent

The plugin achieves this by dynamically adding fields to the user schema and using a before hook on the sign-up route to validate that the required consents have been provided. If a required consent is missing, it throws a BAD_REQUEST error.

Sources: packages/plugins/legal-consent/README.md:3-14, packages/plugins/legal-consent/src/index.ts:192-201

The diagram below shows the data flow when a user signs up with the legalConsent plugin enabled.

Sources: packages/plugins/legal-consent/src/index.ts:192-246

Adapters

Adapters are responsible for integrating Better Auth with specific technologies, such as the Convex backend platform.

Example: Convex Adapter

The Convex adapter includes a utility to automatically generate a schema.ts file. This utility reads the schema definitions from the core Better Auth configuration and all enabled plugins, and then converts them into a format compatible with Convex's defineSchema and defineTable functions. It intelligently merges new fields from plugins with any existing, user-defined fields in the schema file.

Sources: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:20-26

The schema generation process follows these steps:

Sources: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:20-26, packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:60-63

Libraries

Libraries contain shared code that can be used across the ecosystem.

• ui: A library for "Dynamic UI for Better Auth" that uses shadcn, react-hook-form, and zod.
  Sources: packages/libraries/ui/package.json:5, packages/libraries/ui/package.json:28-40
• tests: A collection of utilities to help test Better Auth plugins.
  Sources: packages/libraries/tests/package.json:2

Command Line Interface (CLI)

The @better-auth-kit/cli package provides tools to aid development. A key feature is the db command, which launches a web-based database explorer.

Sources: packages/cli/package.json:2, packages/cli/src/commands/db/index.ts:9

The db command works by:

1. Loading the user's local auth.ts configuration.
2. Starting an Express.js server on port 3572.
3. Injecting a special dbExplorerPlugin into the user's auth instance.
4. Configuring CORS to allow requests from the official better-auth-kit.com frontend (or localhost:3001 in dev mode).
5. Automatically opening the database explorer in the user's default browser.

Sources: packages/cli/src/commands/db/index.ts:22-68

The following sequence diagram shows the startup flow for the db command.

Sources: packages/cli/src/commands/db/index.ts:22-68

Development & Tooling

The project uses a modern toolchain to ensure code quality and development efficiency.

Tool	Purpose	Configuration File
bun	Package manager and JavaScript runtime.	package.json
turbo	High-performance build system for monorepos.	turbo.json (inferred)
biome	Linter and formatter.	biome.json

Sources: package.json:12-14, package.json:18, biome.json

Root Scripts

The main development tasks are managed by scripts in the root package.json.

Script	Description
build	Runs the build script in all workspaces.
dev	Runs the dev script in all workspaces.
format	Formats the entire codebase using Biome.
lint	Lints the entire codebase using Biome.
test	Runs tests in all workspaces.

Sources: package.json:4-10