Contributing
Relevant source files
The following files were used as context for generating this wiki page:Contributions are welcomed to the Better Auth Kit project. This document outlines the standards, structure, and processes for contributing. The project is a collection of plugins, adapters, libraries, and more for Better Auth, managed as a monorepo.
While the formal CONTRIBUTING.md is minimal, it encourages following basic contribution standards. This guide provides more specific details based on the project's structure and tooling.
Sources: README.md:14-17, CONTRIBUTING.md:1-3
Getting Started: Setup and Scripts
The project is a monorepo managed with bun and turbo. To get started, you will need to install dependencies at the root level. The key scripts for development are defined in the root package.json.
Sources: package.json:3-12
Core Scripts
| Script | Description |
|---|---|
build | Executes turbo run build to build all packages in the monorepo. |
dev | Runs turbo run dev --concurrency 20 for parallel development mode across packages. |
format | Formats the entire codebase using biome format --write. |
lint | Lints the codebase using biome lint. |
lint:fix | Lints and automatically fixes issues using biome lint --write. |
check-types | Runs turbo run check-types to perform type-checking across all packages. |
test | Executes turbo test to run all test suites within the monorepo. |
Sources: package.json:4-11
Project Structure
The repository uses bun workspaces to manage a monorepo structure. This organization separates different types of packages into logical directories.
This diagram illustrates the high-level directory structure defined in the workspaces configuration.
Sources: package.json:20-27
| Directory | Purpose |
|---|---|
apps/* | Contains applications, such as the documentation site. |
packages/cli | The command-line interface for the kit. |
packages/plugins/* | Houses various plugins like feedback, legal-consent, and waitlist. |
packages/libraries/* | Contains shared libraries like ui and tests. |
packages/adapters/* | Holds adapters for different backend services, such as convex. |
packages/internal/* | Internal packages used for development and building, like internal-build. |
Sources: package.json:20-27
Code Style and Formatting
The project enforces a consistent code style using Biome. The configuration is defined in biome.json. All contributions should be formatted and linted according to these rules before submission. You can use the bun run format and bun run lint:fix scripts to automate this.
Sources: package.json:6-9, biome.json
Formatter Configuration
The JavaScript/TypeScript formatter is configured with specific style preferences.
| Option | Value | Description |
|---|---|---|
arrowParentheses | always | Always include parentheses around arrow function parameters. |
bracketSameLine | false | Place the > of a multi-line JSX element on a new line. |
bracketSpacing | true | Print spaces between brackets in object literals. |
jsxQuoteStyle | double | Use double quotes for JSX attributes. |
semicolons | always | Always print semicolons at the ends of statements. |
trailingCommas | all | Use trailing commas wherever possible. |
Sources: biome.json:36-45
Linter Rules
The linter is configured to ignore or downgrade several rules to warn to fit the project's needs. Key disabled rules include noDebugger, noConsoleLog, noExplicitAny, and noBannedTypes. This configuration suggests a pragmatic approach to development, but new code should still aim for type safety and clarity.
Sources: biome.json:4-34
Contributing a New Plugin
Plugins are a core part of Better Auth Kit. A typical plugin extends Better Auth by providing new database schema definitions, API endpoints, and hooks.
Plugin Anatomy
A plugin is a self-contained package within packages/plugins/. It generally consists of:
index.ts: The main entry point that exports the plugin factory function.- Schema Definition: Defines new database tables or extends existing ones.
- API Endpoints: Uses
createAuthEndpointto expose new functionality. - Hooks: Can hook into core auth processes (e.g.,
beforesign-up). - Client-side Code: Optional client-side helpers, often in a
client.tsfile. package.json: Defines dependencies, scripts, and package metadata.
The feedback plugin is a good example. It defines a feedback table, a /feedback/submit endpoint, and various configuration options.
This sequence diagram shows the flow of submitting feedback via the feedback plugin's endpoint.
Contributing a New UI Component
The project has a specific workflow for adding new UI components to the ui library, which is based on shadcn.
UI Component Workflow
The following steps must be followed to add a new component:
This process ensures that the new component is correctly registered, built, and integrated into the documentation application and the better-auth-kit registry.