Better Auth Best Practices

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