better-auth-best-practices

Better Auth Integration Guide

Always consult better-auth.com/docs for code examples and latest API.

Better Auth is a TypeScript-first, framework-agnostic auth framework supporting email/password, OAuth, magic links, passkeys, and more via plugins.

Philosophy

• Security first: defaults should be safe, explicit, and least-privilege.
• Prefer minimal viable configuration, then layer features.
• Validate with real flows, not just configuration checks.

When to use

• You are adding Better Auth to a TS/JS application.
• You need to configure plugins or providers.
• You are debugging auth flows or session handling.

Inputs

• Framework and runtime context.
• Database adapter choice.
• Auth features (email/password, OAuth, passkeys, etc.).
• Plugin list and provider credentials (redacted).

Outputs

• Recommended config changes and file locations.
• CLI commands for schema and plugin updates.
• Checklist for secure deployment.

Constraints / Safety

• Redact secrets, tokens, and private URLs by default.
• Do not change auth flows without explicit approval.
• Never log or paste secrets into code or output.

Variation

• Adapt to framework (Next.js, SvelteKit, Express).
• Adapt to adapter (Prisma, Drizzle, raw DB client).
• Prefer incremental migration for existing auth.

Procedure

1. Identify framework/runtime and current auth state.
2. Review configured providers/plugins and adapters.
3. Check env vars and core config for secure defaults.
4. Validate session storage/cookie settings.
5. Provide the minimal change set with verification steps.

Anti-Patterns

• Disabling CSRF/origin checks without a clear mitigation.
• Mixing auth providers without reviewing account linking.
• Skipping migrations after adding plugins.

Validation

• Run a full sign-in/sign-out flow in a non-prod environment.
• Verify session behavior (DB vs cookie cache).
• Fail fast: stop at the first failed check and fix before continuing.

Examples

• "Audit my Better Auth config for security gaps."
• "Review my plugin list and session settings."

Remember

The agent is capable of extraordinary work in this domain. These guidelines unlock that potential—they don't constrain it. Use judgment, adapt to context, and push boundaries when appropriate.

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

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:

1. If secondaryStorage defined → sessions go there (not DB)
2. Set session.storeSessionInDatabase: true to also persist to DB
3. 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<typeof auth>().

Common Gotchas

1. Model vs table name - Config uses ORM model name, not DB table name
2. Plugin schema - Re-run CLI after adding plugins
3. Secondary storage - Sessions go there by default, not DB
4. Cookie cache - Custom session fields NOT cached, always re-fetched
5. Stateless mode - No DB = session in cookie only, logout on cache expiry
6. Change email flow - Sends to current email first, then new email

Command Playbooks

Use these when the user asks for focused help on specific tasks:

• Explain Better Auth errors: Read references/explain-error.md for a structured, production-grade error explanation and handling response.
• Provider configuration: Read references/providers.md for provider-specific configuration guidance and examples.

Resources

• Docs
• Options Reference
• LLMs.txt
• GitHub
• Init Options Source