Skip to content

Latest commit

 

History

History
104 lines (75 loc) · 2.8 KB

CLAUDE.md

File metadata and controls

104 lines (75 loc) · 2.8 KB

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

# 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(): 
    /**
 * @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 + Fumadocs
  • 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
  • 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