Contributing to BetterAuth

Thank you for your interest in contributing to Better Auth! This guide is a concise guide to contributing to Better Auth.

Getting Started

Before diving in, here are a few important resources:

• Take a look at our existing issues and pull requests
• Join our community discussions in Discord

Development Setup

To get started with development:

# Replace YOUR-USERNAME with your GitHub username
git clone https://github.com/YOUR-USERNAME/better-auth.git
cd better-auth

pnpm install

cp -n ./docs/.env.example ./docs/.env

Making changes

Once you have an idea of what you want to contribute, you can start making changes. Here are some steps to get started:

# Make sure you're on main
git checkout main

# Pull latest changes
git pull upstream main

# Create and switch to a new branch
git checkout -b feature/your-feature-name

pnpm dev

pnpm -F docs dev

Issues and Bug Fixes

• Check our GitHub issues for tasks labeled good first issue
• When reporting bugs, include steps to reproduce and expected behavior
• Comment on issues you'd like to work on to avoid duplicate efforts

Framework Integrations

We welcome contributions to support more frameworks:

• Focus on framework-agnostic solutions where possible
• Keep integrations minimal and maintainable
• All integrations currently live in the main package

Plugin Development

• For core plugins: Open an issue first to discuss your idea
• For community plugins: Feel free to develop independently
• Follow our plugin architecture guidelines

Documentation

• Fix typos and errors
• Add examples and clarify existing content
• Ensure documentation is up to date with code changes

Testing

We use Vitest for testing. Place test files next to the source files they test:

import { describe, it, expect } from "vitest";
import { getTestInstance } from "./test-utils/test-instance";

describe("Feature", () => {
    it("should work as expected", async () => {
        const { client } = await getTestInstance();
        // Test code here
        expect(result).toBeDefined();
    });
});

Using the Test Instance Helper

The test instance helper now includes improved async context support for managing user sessions:

const { client, runWithUser, signInWithTestUser } = await getTestInstance();

// Run tests with a specific user context
await runWithUser("user@example.com", "password", async (headers) => {
    // All client calls within this block will use the user's session
    const response = await client.getSession();
    // headers are automatically applied
});

// Or use the test user with async context
const { runWithDefaultUser } = await signInWithTestUser();
await runWithDefaultUser(async (headers) => {
    // Code here runs with the test user's session context
});

Testing Best Practices

• Write clear commit messages
• Update documentation to reflect your changes
• Add tests for new features
• Follow our coding standards
• Keep pull requests focused on a single change

Need Help?

Don't hesitate to ask for help! You can:

• Open an issue with questions
• Join our community discussions
• Reach out to project maintainers

Thank you for contributing to Better Auth!