1---
2name: better-auth-best-practices
3description: Configure Better Auth server and client, set up database adapters, manage sessions, add plugins, and handle environment variables. Use when users mention Better Auth, betterauth, auth.ts, or need to set up TypeScript authentication with email/password, OAuth, or plugin configuration.
4---
5 
6# Better Auth Integration Guide
7 
8**Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.**
9 
10---
11 
12## Setup Workflow
13 
141. Install: `npm install better-auth`
152. Set env vars: `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`
163. Create `auth.ts` with database + config
174. Create route handler for your framework
185. Run `npx @better-auth/cli@latest migrate`
196. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`
20 
21---
22 
23## Quick Reference
24 
25### Environment Variables
26- `BETTER_AUTH_SECRET` - Encryption secret (min 32 chars). Generate: `openssl rand -base64 32`
27- `BETTER_AUTH_URL` - Base URL (e.g., `https://example.com`)
28 
29Only define `baseURL`/`secret` in config if env vars are NOT set.
30 
31### File Location
32CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.
33 
34### CLI Commands
35- `npx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
36- `npx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
37- `npx @better-auth/cli mcp --cursor` - Add MCP to AI tools
38 
39**Re-run after adding/changing plugins.**
40 
41---
42 
43## Core Config Options
44 
45| Option | Notes |
46|--------|-------|
47| `appName` | Optional display name |
48| `baseURL` | Only if `BETTER_AUTH_URL` not set |
49| `basePath` | Default `/api/auth`. Set `/` for root. |
50| `secret` | Only if `BETTER_AUTH_SECRET` not set |
51| `database` | Required for most features. See adapters docs. |
52| `secondaryStorage` | Redis/KV for sessions & rate limits |
53| `emailAndPassword` | `{ enabled: true }` to activate |
54| `socialProviders` | `{ google: { clientId, clientSecret }, ... }` |
55| `plugins` | Array of plugins |
56| `trustedOrigins` | CSRF whitelist |
57 
58---
59 
60## Database
61 
62**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance.
63 
64**ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`.
65 
66**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"`.
67 
68---
69 
70## Session Management
71 
72**Storage priority:**
731. If `secondaryStorage` defined → sessions go there (not DB)
742. Set `session.storeSessionInDatabase: true` to also persist to DB
753. No database + `cookieCache` → fully stateless mode
76 
77**Cookie cache strategies:**
78- `compact` (default) - Base64url + HMAC. Smallest.
79- `jwt` - Standard JWT. Readable but signed.
80- `jwe` - Encrypted. Maximum security.
81 
82**Key options:** `session.expiresIn` (default 7 days), `session.updateAge` (refresh interval), `session.cookieCache.maxAge`, `session.cookieCache.version` (change to invalidate all sessions).
83 
84---
85 
86## User & Account Config
87 
88**User:** `user.modelName`, `user.fields` (column mapping), `user.additionalFields`, `user.changeEmail.enabled` (disabled by default), `user.deleteUser.enabled` (disabled by default).
89 
90**Account:** `account.modelName`, `account.accountLinking.enabled`, `account.storeAccountCookie` (for stateless OAuth).
91 
92**Required for registration:** `email` and `name` fields.
93 
94---
95 
96## Email Flows
97 
98- `emailVerification.sendVerificationEmail` - Must be defined for verification to work
99- `emailVerification.sendOnSignUp` / `sendOnSignIn` - Auto-send triggers
100- `emailAndPassword.sendResetPassword` - Password reset email handler
101 
102---
103 
104## Security
105 
106**In `advanced`:**
107- `useSecureCookies` - Force HTTPS cookies
108- `disableCSRFCheck` - ⚠️ Security risk
109- `disableOriginCheck` - ⚠️ Security risk  
110- `crossSubDomainCookies.enabled` - Share cookies across subdomains
111- `ipAddress.ipAddressHeaders` - Custom IP headers for proxies
112- `database.generateId` - Custom ID generation or `"serial"`/`"uuid"`/`false`
113 
114**Rate limiting:** `rateLimit.enabled`, `rateLimit.window`, `rateLimit.max`, `rateLimit.storage` ("memory" | "database" | "secondary-storage").
115 
116---
117 
118## Hooks
119 
120**Endpoint hooks:** `hooks.before` / `hooks.after` - Array of `{ matcher, handler }`. Use `createAuthMiddleware`. Access `ctx.path`, `ctx.context.returned` (after), `ctx.context.session`.
121 
122**Database hooks:** `databaseHooks.user.create.before/after`, same for `session`, `account`. Useful for adding default values or post-creation actions.
123 
124**Hook context (`ctx.context`):** `session`, `secret`, `authCookies`, `password.hash()`/`verify()`, `adapter`, `internalAdapter`, `generateId()`, `tables`, `baseURL`.
125 
126---
127 
128## Plugins
129 
130**Import from dedicated paths for tree-shaking:**
131```
132import { twoFactor } from "better-auth/plugins/two-factor"
133```
134NOT `from "better-auth/plugins"`.
135 
136**Popular plugins:** `twoFactor`, `organization`, `passkey`, `magicLink`, `emailOtp`, `username`, `phoneNumber`, `admin`, `apiKey`, `bearer`, `jwt`, `multiSession`, `sso`, `oauthProvider`, `oidcProvider`, `openAPI`, `genericOAuth`.
137 
138Client plugins go in `createAuthClient({ plugins: [...] })`.
139 
140---
141 
142## Client
143 
144Import from: `better-auth/client` (vanilla), `better-auth/react`, `better-auth/vue`, `better-auth/svelte`, `better-auth/solid`.
145 
146Key methods: `signUp.email()`, `signIn.email()`, `signIn.social()`, `signOut()`, `useSession()`, `getSession()`, `revokeSession()`, `revokeSessions()`.
147 
148---
149 
150## Type Safety
151 
152Infer types: `typeof auth.$Infer.Session`, `typeof auth.$Infer.Session.user`.
153 
154For separate client/server projects: `createAuthClient<typeof auth>()`.
155 
156---
157 
158## Common Gotchas
159 
1601. **Model vs table name** - Config uses ORM model name, not DB table name
1612. **Plugin schema** - Re-run CLI after adding plugins
1623. **Secondary storage** - Sessions go there by default, not DB
1634. **Cookie cache** - Custom session fields NOT cached, always re-fetched
1645. **Stateless mode** - No DB = session in cookie only, logout on cache expiry
1656. **Change email flow** - Sends to current email first, then new email
166 
167---
168 
169## Resources
170 
171- [Docs](https://better-auth.com/docs)
172- [Options Reference](https://better-auth.com/docs/reference/options)
173- [LLMs.txt](https://better-auth.com/llms.txt)
174- [GitHub](https://github.com/better-auth/better-auth)
175- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)