better-auth-best-practices

Better Auth Integration Guide Always consult better-auth.com/docs for code examples and latest API. Setup Workflow Install: npm install better-auth Set env vars: BETTER_AUTH_SECRET and BETTER_AUTH_URL Create auth.ts with database + config Create route handler for your framework Run npx @better-auth/cli@latest migrate 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 npx @better-auth/cli@latest migrate - Apply schema (built-in adapter) npx @better-auth/cli@latest generate - Generate schema for Prisma/Drizzle npx @better-auth/cli 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). 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() . 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 Resources Docs Options Reference LLMs.txt GitHub Init Options Source