System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:Better Auth Kit is a collection of plugins, adapters, libraries, and tools designed to extend the functionality of the Better Auth framework. The project is structured as a monorepo, managed by Bun and Turbo, which allows for modular development and efficient code sharing between its various components. This architecture enables developers to pick and choose the features they need, from legal consent enforcement to database integration with backends like Convex.
The core design philosophy is centered around a plugin-based system. Each package within the monorepo serves a distinct purpose, whether it's providing a new feature, adapting to a specific database, offering UI components, or supplying developer tools. This modularity ensures that the core authentication system remains lean while being highly extensible.
Sources: README.md, package.json
Monorepo Structure
The project utilizes a monorepo structure to manage its diverse set of packages. This is defined in the root package.json file under the workspaces key. The structure facilitates dependency management and streamlined development workflows across the entire toolkit.
Sources: package.json:20-27
Package Organization
The packages are organized into logical directories based on their function.
This diagram illustrates the high-level organization of the monorepo.
Source: package.json:20-27
The roles of these package types are summarized below:
| Directory | Purpose | Examples | Source |
|---|---|---|---|
apps | Contains full-fledged applications, such as the documentation site. | docs | package.json:21 |
packages/cli | The command-line interface for developers. | @better-auth-kit/cli | package.json:22 |
packages/plugins | Extend Better Auth with new features like legal consent or feedback forms. | @better-auth-kit/legal-consent, @better-auth-kit/feedback | package.json:23 |
packages/libraries | Shared code, such as UI components or testing utilities. | ui, @better-auth-kit/tests | package.json:24 |
packages/adapters | Provide compatibility layers for different database backends. | convex | package.json:25 |
packages/internal | Internal utilities used for building and maintaining the monorepo. | @better-auth-kit/internal-build | package.json:26 |
Core Components
Plugins
Plugins are the primary mechanism for extending Better Auth's functionality. They can introduce new API endpoints, add fields to the database schema, and execute hooks at various points in the authentication lifecycle.
A typical plugin, like legal-consent, exports a function that returns a BetterAuthPlugin object. This object defines the plugin's id, its schema modifications, and its hooks.
The following sequence diagram shows how the legal-consent plugin intercepts a sign-up request to enforce that the Terms of Service are accepted.
Adapters
Adapters are responsible for bridging Better Auth with various database technologies. The convex adapter, for instance, includes logic to dynamically generate a schema.ts file that is compatible with the Convex backend.
Convex Schema Generation
The schema generation process in the Convex adapter is a key feature. It parses an existing schema.ts file, merges it with the base schema from Better Auth and any schemas defined by active plugins, and then writes the new, combined schema back to the file.
This flow diagram outlines the schema generation process:
The generator uses regular expressions to find and parse the defineSchema block and its tables. It then converts the abstract schema definitions from Better Auth plugins into Convex-specific v.type() syntax.
Source: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:5-8
Command-Line Interface (CLI)
The @better-auth-kit/cli package provides developers with tools to manage and inspect their Better Auth application. A key command is db, which launches a database explorer.
The db command works by:
- Loading the user's
auth.tsconfiguration file. - Starting an Express server on a dedicated port (
3572). - Injecting a special
dbExplorerPlugininto the user's auth instance. - Configuring CORS to allow requests from the Better Auth Kit website.
- Opening the database explorer web interface in the user's default browser.
Source: packages/cli/src/commands/db/index.ts:25-66
Build and Development Workflow
The project uses a combination of bun and turbo to manage its build and development processes.
Tooling
| Tool | Role | Source |
|---|---|---|
bun | The JavaScript runtime and package manager. | package.json:18 |
turbo | The monorepo build system orchestrator. | package.json:13 |
biome | The code formatter and linter. | package.json:12, biome.json |
Build Process
The build process is defined in turbo.json and executed via scripts in the root package.json. The turbo run build command triggers the build script in each package.
Most packages use the @better-auth-kit/internal-build utility, which provides a standardized build function. This function uses Bun.build to compile TypeScript source files from src into JavaScript files in a dist directory, generating sourcemaps and minifying the output.
This diagram shows the package build flow:
The build configuration in turbo.json defines the dependency pipeline, ensuring that packages are built in the correct order. It also configures caching to speed up subsequent builds.
Summary
The Better Auth Kit architecture is a well-defined, modular system built for extensibility. Its monorepo structure, managed by Turbo and Bun, allows for clear separation of concerns between plugins, adapters, libraries, and tools. The plugin-based design is central to its philosophy, enabling developers to easily add features without modifying the core. The inclusion of powerful developer tools like a CLI and a sophisticated adapter system for backends like Convex demonstrates a commitment to a robust and developer-friendly experience.