Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
226 lines (153 loc) · 6.56 KB

CONTRIBUTING.md

File metadata and controls

226 lines (153 loc) · 6.56 KB

Contributing to Better Auth

Hi, we really appreciate your interest in contributing to Better Auth. This guide will help you get started. Your contributions make Better Auth even better for everyone. Before you begin, please take a moment to review the following guidelines.

By participating in this project, you agree to abide by our Code of Conduct.

Repository Setup

  1. Fork the repository and clone it locally:

    git clone https://github.com/your-username/better-auth.git
cd better-auth

  2. Install Node.js (LTS version recommended)

    Note: This project is configured to use nvm to manage the local Node.js version, as such this is the simplest way to get you up and running.

    Once installed, use:

    nvm install
nvm use

    Alternatively, see Node.js installation for other supported methods.

  3. Install pnpm

    Note: This project is configured to manage pnpm via corepack. Once installed, upon usage you’ll be prompted to install the correct pnpm version

    Alternatively, use npm to install it:

    npm install -g pnpm

  4. Install project dependencies:

    pnpm install

  5. Build the project:

    pnpm build

Testing

Bug fixes and new features must include tests.

Run the full test suite:

pnpm test

Or filter by file or directory:

pnpm vitest packages/better-auth/src/plugins/organization --run

Unit Tests

Use getTestInstance() from better-auth/test to set up test instances:

import { getTestInstance } from "better-auth/test";

const { client, auth } = await getTestInstance({
  plugins: [organization()],
});

Database Adapter Tests

Adapter tests require Docker containers. Start them before running adapter tests:

Note: On macOS, the MSSQL container requires Rosetta emulation and at least 2 GB of allocated memory.

docker compose up -d

E2E Tests

End-to-end tests live in e2e/ and are split into three suites: smoke, adapter, and integration.

Regression Tests

When writing a test for a specific GitHub issue, add a @see comment:

/**
 * @see https://github.com/better-auth/better-auth/issues/1234
 */
it("should handle the previously broken behavior", async () => {
  // ...
});

Documentation

The documentation site lives in docs/ and content is organized under docs/content/docs/ by topic.

To run the docs locally:

pnpm -F docs dev

When making changes to public APIs, please update the relevant documentation.

Issue Guidelines

Before opening an issue, search existing issues to avoid duplicates. We provide templates to help you get started.

Bug Reports

Use the bug report template. Provide a clear description of the bug with steps to reproduce and a minimal reproduction.

Feature Requests

New features start with discussion. Open a feature request describing the problem, your proposed solution, and how it would benefit the project. This gives us room to align on scope and API shape before anyone writes code.

Security Reports

Do not open a public issue for security vulnerabilities. Email security@better-auth.com instead. See SECURITY.md for details.

Pull Request Guidelines

Note

For new features, please open an issue first to discuss before moving forward. We do not review large feature PRs opened without going through an issue first.

Code Formatting and Linting

Lefthook runs linting, formatting, and spell checking in parallel on every commit. Additional checks like dependency linting (knip), type checking, and tests run in CI.

To skip a specific hook by command name, use LEFTHOOK_EXCLUDE:

LEFTHOOK_EXCLUDE=spell git commit -m "your message"

Run pnpm typecheck and make sure it passes before opening your PR.

Branch Targeting

  • main is the stable track. It ships bug fixes, security work, additive improvements, and behavior changes that do not require user action. New capabilities can land here too as long as they are well-tested, non-breaking, and safe to adopt immediately.
  • next is the beta track. It ships new features, refactors, and breaking changes, after a beta cycle that gives users a window to adapt.

Automation moves PRs with minor or major changesets from main to next for you.

Changesets

PRs that touch packages/** need a changeset before they can be merged. Run pnpm changeset when you're ready to submit, or update it during review if your changes evolve. The CLI walks you through picking the affected packages, a bump type, and a short user-facing description for the changelog. Commit the generated file with your PR.

Pick the bump type based on user impact:

  • patch for bug fixes and additive changes existing users don't need to know about.
  • minor or major for anything existing users need to be aware of (see Branch Targeting).

If you're not sure whether your change needs one, a maintainer will handle it before merge.

Submitting a PR

  1. Open a pull request against the main branch.

  2. PR titles must follow the Conventional Commits format, with an optional scope for the affected package or feature:

    `feat(scope): description` or
`fix(scope): description` or
`perf: description` or
`docs: description` or
`chore: description` etc.
    • The subject must start with a lowercase letter.
    • Use docs when changes are confined to docs/.
    • Append ! for breaking changes (e.g. feat(scope)!: description). These go through next, not main.

  3. In your PR description:

    • Clearly describe what you changed and why
    • Reference related issues (e.g. "Closes #1234")
    • List any potential breaking changes
    • Add screenshots for UI changes

AI Policy

We welcome AI-assisted contributions, whether code or issue reports, as long as they solve a real problem. Code must follow our coding standards and include appropriate tests and documentation. You should also review and understand what you're submitting well enough to discuss it. PRs and issues that do not meet these guidelines will be closed.