# 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

## Règles

@nextjs-16.x.md