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.
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.
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.
Prefer a version explicitly named by the user.
Otherwise, inspect the resolved better-auth version in the lockfile, falling back to the package manifest when no lockfile is available.
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.
npx auth@latest generate - Generate schema for Prisma/Drizzle
npx auth@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. For Postgres, also supports postgres (postgres.js) and @neondatabase/serverless.
ORM adapters: Import from better-auth/adapters/drizzle, better-auth/adapters/prisma, better-auth/adapters/mongodb.
Drizzle provider values:"pg" (PostgreSQL), "mysql" (MySQL), "sqlite" (SQLite). Must match the driver used.
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).
For separate client/server projects: createAuthClient<typeof auth>().
Common Gotchas
Model vs table name - Config uses ORM model name, not DB table name
Plugin schema - Re-run CLI after adding plugins
Secondary storage - Sessions go there by default, not DB
Cookie cache - Custom session fields NOT cached, always re-fetched
Stateless mode - No DB = session in cookie only, logout on cache expiry
Change email flow - Sends to current email first, then new email
Drizzle: db not initialized - drizzleAdapter(db, ...) requires a db instance from drizzle(). See create-auth skill for setup examples (node-postgres, postgres.js, Neon).
Drizzle: missing drizzle.config.ts - drizzle-kit commands require a drizzle.config.ts pointing to the generated schema file and DB credentials.
