better-auth-best-practices

# Better Auth Integration Guide **Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.** --- ## Setup Workflow 1. Install: `bun add 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 `bunx @better-auth/cli@latest migrate` 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. ### CLI Commands - `bunx @better-auth/cli@latest migrate` - Apply schema (built-in adapter) - `bunx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle - `bunx @better-auth/cli@latest mcp --cursor` - Add MCP to AI tools **Re-run after adding/changing plugins.** --- ## Core Config Options | Option | Notes | |--------|-------| | `appName` | Optional display name | | `baseURL` | Only if `BETTER_AUTH_URL` not set | | `basePath` | Default `/api/auth`. Set `/` for root. | | `secret` | Only if `BETTER_AUTH_SECRET` not set | | `database` | Required for most features. See adapters docs. | | `secondaryStorage` | Redis/KV for sessions & rate limits | | `emailAndPassword` | `{ enabled: true }` to activate | | `socialProviders` | `{ google: { clientId, clientSecret }, ... }` | | `plugins` | Array of plugins | | `trustedOrigins` | CSRF whitelist | --- ## Database **Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance. **ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`. **Critical:** Better Auth uses adapter model names, NOT underlying table names. If Prisma model is `User` mapping to table `users`, use `modelName: "user"` (Prisma reference), not `"users"`. --- ## Session Management **Storage priority:** 1. If `secondaryStorage` defined → sessions go there (not DB) 2. Set `session.storeSessionInDatabase: true` to also persist to DB 3. No database + `cookieCache` → fully stateless mode **Cookie cache strategies:** - `compact` (default) - Base64url + HMAC. Smallest. - `jwt` - Standard JWT. Readable but signed. - `jwe` - Encrypted. Maximum security. **Key options:** `session.expiresIn` (default 7 days), `session.updateAge` (refresh interval), `session.cookieCache.maxAge`, `session.cookieCache.version` (change to invalidate all sessions). --- ## User & Account Config **User:** `user.modelName`, `user.fields` (column mapping), `user.additionalFields`, `user.changeEmail.enabled` (disabled by default), `user.deleteUser.enabled` (disabled by default). **Account:** `account.modelName`, `account.accountLinking.enabled`, `account.storeAccountCookie` (for stateless OAuth). **Required for registration:** `email` and `name` fields. --- ## Email Flows - `emailVerification.sendVerificationEmail` - Must be defined for verification to work - `emailVerification.sendOnSignUp` / `sendOnSignIn` - Auto-send triggers - `emailAndPassword.sendResetPassword` - Password reset email handler --- ## Security **In `advanced`:** - `useSecureCookies` - Force HTTPS cookies - `disableCSRFCheck` - ⚠️ Security risk - `disableOriginCheck` - ⚠️ Security risk - `crossSubDomainCookies.enabled` - Share cookies across subdomains - `ipAddress.ipAddressHeaders` - Custom IP headers for proxies - `database.generateId` - Custom ID generation or `"serial"`/`"uuid"`/`false` **Rate limiting:** `rateLimit.enabled`, `rateLimit.window`, `rateLimit.max`, `rateLimit.storage` ("memory" | "database" | "secondary-storage"). --- ## Hooks **Endpoint hooks:** `hooks.before` / `hooks.after` - Array of `{ matcher, handler }`. Use `createAuthMiddleware`. Access `ctx.path`, `ctx.context.returned` (after), `ctx.context.session`. **Database hooks:** `databaseHooks.user.create.before/after`, same for `session`, `account`. Useful for adding default values or post-creation actions. **Hook context (`ctx.context`):** `session`, `secret`, `authCookies`, `password.hash()`/`verify()`, `adapter`, `internalAdapter`, `generateId()`, `tables`, `baseURL`. --- ## Plugins **Import from dedicated paths for tree-shaking:** ``` import { twoFactor } from "better-auth/plugins/two-factor" ``` NOT `from "better-auth/plugins"`. **Popular plugins:** `twoFactor`, `organization`, `passkey`, `magicLink`, `emailOtp`, `username`, `phoneNumber`, `admin`, `apiKey`, `bearer`, `jwt`, `multiSession`, `sso`, `oauthProvider`, `oidcProvider`, `openAPI`, `genericOAuth`. Client plugins go in `createAuthClient({ plugins: [...] })`. --- ## Client Import from: `better-auth/client` (vanilla), `better-auth/react`, `better-auth/vue`, `better-auth/svelte`, `better-auth/solid`. Key methods: `signUp.email()`, `signIn.email()`, `signIn.social()`, `signOut()`, `useSession()`, `getSession()`, `revokeSession()`, `revokeSessions()`. --- ## Type Safety Infer types: `typeof auth.$Infer.Session`, `typeof auth.$Infer.Session.user`. For separate client/server projects: `createAuthClient<typeof auth>()`. --- ## Common Gotchas 1. **Model vs table name** - Config uses ORM model name, not DB table name 2. **Plugin schema** - Re-run CLI after adding plugins 3. **Secondary storage** - Sessions go there by default, not DB 4. **Cookie cache** - Custom session fields NOT cached, always re-fetched 5. **Stateless mode** - No DB = session in cookie only, logout on cache expiry 6. **Change email flow** - Sends to current email first, then new email --- ## Resources - [Docs](https://better-auth.com/docs) - [Options Reference](https://better-auth.com/docs/reference/options) - [LLMs.txt](https://better-auth.com/llms.txt) - [GitHub](https://github.com/better-auth/better-auth) - [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)