Better Auth server/client setup: `auth.ts`, generated schema, DB adapters, sessions, cookies, env vars, and plugins. Use when mentioning Better Auth, betterauth, auth handlers, OAuth, email/password, or session configuration.
metadata
{"author":"epicenter","version":"1.0"}
Better Auth Integration Guide
Reference Repositories
Better Auth — TypeScript authentication framework with plugins
Upstream Grounding
When Better Auth API signatures, adapter behavior, generated schema, plugin options, session storage, cookie behavior, or security defaults affect correctness, ask DeepWiki a narrow question against better-auth/better-auth before relying on memory. Use it to orient, then verify decisive details against local installed types, source, or official docs before changing code.
Skip DeepWiki for stable setup basics already documented below.
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
bun x @better-auth/cli@latest migrate - Apply schema (built-in adapter)
bun x @better-auth/cli@latest generate - Generate schema for Prisma/Drizzle
bun x @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:
If secondaryStorage defined → sessions go there (not DB)
Set session.storeSessionInDatabase: true to also persist to DB
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).
Mount Better Auth handlers for both GET and POST auth paths.
Register credentialed CORS before Better Auth when browser callers use cookies. Coordinate credentials: true, trustedOrigins, secure cookies, and origin checks.
Treat baseURL as security-sensitive: it drives redirects, issuer URLs, cookie behavior, and OAuth validation. Dynamic base URLs need explicit host or origin validation.
Treat trustedOrigins as a CSRF and redirect boundary, not a convenience list.
Do not disable CSRF or origin checks in production. disableOriginCheck also weakens CSRF protection.
Make secure cookie behavior explicit in production, even if Better Auth can infer it from HTTPS.
If secondaryStorage is configured, sessions may not persist to the database unless session.storeSessionInDatabase is set. Put OAuth verification records in durable storage when KV consistency or cross-isolate reads matter.
For OAuth provider work, document PKCE, trusted clients, JWT or JWKS signing choices, audience and issuer validation, discovery endpoints, and resource-server token verification.
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.
