# CLAUDE.md

This file provides guidance to AI assistants (Claude Code, Cursor, etc.)
when working with code in this repository.

## Project Overview

Better Auth is a comprehensive, framework-agnostic authentication
framework for TypeScript.

## Development Commands

```bash
# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run all tests
pnpm test

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm typecheck

# Format code
pnpm format

# Check formatting
pnpm format:check
```

Do not run `pnpm test` directly because it runs tests in all packages,
which takes a long time, use `vitest /path/to/<test-file> -t <pattern>` to
run specific tests.

## Architecture

### Package Structure

* `packages/better-auth` - Main authentication library
* `packages/core` - Core utilities and types
* `packages/cli` - Command-line interface
* `packages/*` - Database adapters, plugins, and integrations
* `docs/` - Documentation site (Next.js + Fumadocs)
* `demo/` - Demo apps
* `e2e/` - End-to-end tests (smoke, adapter, integration)

## Code Style

* Formatter: Biome (tabs for code, 2-space for JSON)
* Avoid unsafe typecasts or types like `any`
* Avoid classes, use functions and objects
* Do not use runtime-specific feature like `Buffer` in codebase except
  test, use `Uint8Array` instead

## Testing

* Most of the tests use Vitest
* Some tests under `e2e/` directory use Playwright
* Adapter tests require Docker containers running (`docker compose up -d`)
* Consider using test helpers like `getTestInstance()` from
  `better-auth/test` first
* If a test is to prevent regression of a specific numbered GitHub issue,
  add a JSDoc `@see` comment with the issue URL above the `it()` or `describe()`:
  ```typescript
  /**
   * @see https://github.com/better-auth/better-auth/issues/{issue_number}
   */
  it("should handle the previously broken behavior", async () => {
    // ...
  });
  ```

## Documentation

* Please update the documentation when you make changes to the public API
* Documentation is located in the `docs/` directory, built with
  [Next.js](https://nextjs.org/docs/llms.txt) + [Fumadocs](https://www.fumadocs.dev/llms.txt)
* Content lives in `docs/content/docs/` organized by topic (authentication,
  adapters, concepts, guides, plugins, examples, reference)

## Git Workflow

* PRs should target the `canary` branch
* Commit format: `feat(scope): description` or `fix(scope): description`,
  following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
* Use `docs:` for documentation, `chore:` for non-functional changes

## Postmortems

Check `postmortem/` directory for lessons learned from past issues.

## After Everything is done

**Unless the user asked for it or you are working on CI, DO NOT COMMIT**

* Make sure `pnpm format:check`, `pnpm lint` and `pnpm typecheck` pass