better-auth-best-practices

Better Auth Integration Guide

Documentation Version

Use documentation that matches the Better Auth version installed in the project. APIs and plugin names can differ across maintained release lines.

1. Prefer a version explicitly named by the user.
2. Otherwise, inspect the resolved better-auth version in the lockfile, falling back to the package manifest when no lockfile is available.
3. When the Better Auth MCP is available, call get_doc with /llms.txt to resolve that package version to a documentation identifier. Pass the identifier to every search_docs call and pass result paths to get_doc unchanged.
4. Without MCP, start at better-auth.com/llms.txt and follow the matching version index.
5. Use the latest documentation only when the project version cannot be determined or the user explicitly asks about the latest release or an upgrade.

When planning an upgrade, separate guidance for the currently installed version from guidance for the target version.

---

Setup Workflow

1. Install: npm install better-auth
2. Set env vars: BETTER_AUTH_SECRET and BETTER_AUTH_URL
3. Create auth.ts with database + config
4. Create route handler for your framework
5. Run migrations:
   • Built-in adapter: npx auth@latest migrate
   • Drizzle: npx auth@latest generate --output src/db/auth-schema.ts then npx drizzle-kit push (dev) or npx drizzle-kit generate && npx drizzle-kit migrate (prod)
   • Prisma: npx auth@latest generate --output prisma/schema.prisma then npx prisma migrate dev
6. Verify: call GET /api/auth/ok — should return { status: "ok" }

---

Quick Reference

Environment Variables

• BETTER_AUTH_SECRET - Encryption secret (min 32 chars). Generate: openssl rand -base64 32
• BETTER_AUTH_URL - Base URL (e.g., https://example.com)

Only define baseURL/secret in config if env vars are NOT set.

File Location

CLI looks for auth.ts in: ./, ./lib, ./utils, or under ./src. Use --config for custom path.