---
title: Contributing to BetterAuth
description: A concise guide to 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:

<Callout type="warn">
  Make sure you have <Link href="https://nodejs.org/en/download">Node.JS</Link>{" "}
  installed, preferably on LTS.
</Callout>

<Steps>

    <Step>
        ### 1. Fork the repository

        Visit https://github.com/better-auth/better-auth

        Click the "Fork" button in the top right.

    </Step>

    <Step>
        ### 2. Clone your fork

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

    <Step>
        ### 3. Install dependencies

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

        ```bash
        pnpm install
        ```
    </Step>

    <Step>
        ### 4. Prepare ENV files

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

        ```bash
        cp -n ./docs/.env.example ./docs/.env
        ```
    </Step>

</Steps>

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

<Steps>
    <Step>
        ### 1. Create a new branch

        ```bash
        # 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
        ```
    </Step>
    <Step>
        ### 2. Start development server

        Start the development server:

        ```bash
        pnpm dev
        ```

        To start the docs server:

        ```bash
        pnpm -F docs dev
        ```
    </Step>
    <Step>
        ### 3. Make Your Changes

        * Make your changes to the codebase.

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

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

    </Step>

</Steps>


### Issues and Bug Fixes

- Check our [GitHub issues](https://github.com/better-auth/better-auth/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:

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

```ts
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 <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!