# Contributing to BetterAuth (/docs/reference/contributing)

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 [#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 [#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 [#1-fork-the-repository]

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

    Click the "Fork" button in the top right.
  </Step>

  <Step>
    ### 2. Clone your fork [#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 [#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 [#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 [#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 [#1-create-a-new-branch]

    ```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
    ```
  </Step>

  <Step>
    ### 2. Start development server [#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 [#3-make-your-changes]

    * 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>)
  </Step>
</Steps>

### Issues and Bug Fixes [#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 [#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

### Social Provider Integrations [#social-provider-integrations]

Review the [social provider contribution policy](https://github.com/better-auth/better-auth/blob/main/CONTRIBUTING.md#social-provider-integrations) before proposing a built-in social provider or provider helper.

Community helpers can be developed independently using the [Generic OAuth plugin](/docs/plugins/generic-oauth) and submitted for listing under [Other Social Providers](/docs/authentication/other-social-providers#community-provider-helpers).

### Plugin Development [#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 [#documentation]

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

## Testing [#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 [#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 [#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? [#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!