mirror of
https://github.com/better-auth/better-auth.git
synced 2026-10-19 11:24:57 -05:00
8a9de0226f
Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Taesu <bytaesu@users.noreply.github.com> Co-authored-by: Alex Yang <himself65@outlook.com>
105 lines
2.8 KiB
Markdown
105 lines
2.8 KiB
Markdown
# 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
|