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 <Link href="https://github.com/better-auth/better-auth/issues">issues</Link> and <Link href="https://github.com/better-auth/better-auth/pulls">pull requests</Link>
• Join our community discussions in <Link href="https://discord.gg/better-auth">Discord</Link>

Development Setup

To get started with development:

Visit [https://github.com/better-auth/better-auth](https://github.com/better-auth/better-auth)

Click the "Fork" button in the top right.

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

Make sure you have <Link href="https://pnpm.io/installation">pnpm</Link> installed!

```bash
pnpm install
```

Copy the example env file to create your new `.env` file.

```bash
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:

```bash
# Add upstream remote (if not already added)
git remote add upstream https://github.com/better-auth/better-auth.git

# 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
```

Start the development server:

```bash
pnpm dev
```

To start the docs server:

```bash
pnpm -F docs dev
```

* Make your changes to the codebase.

* Write tests if needed. (Read more about <Link href="/docs/reference/contributing#testing">testing</Link>)

* Update documentation. (Read more about <Link href="/docs/reference/contributing#documentation">documenting</Link>)

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("[email protected]", "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 <Link href="https://github.com/better-auth/better-auth/issues">issue</Link> with questions
• Join our <Link href="https://discord.gg/better-auth">community discussions</Link>
• Reach out to project maintainers

Thank you for contributing to Better Auth!