Better Auth Integration Guide Skill

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.

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

When to Apply This Skill

Use this pattern when you need to:

Configure Better Auth server/client setup in TypeScript projects.
Wire environment variables, database adapters, and CLI migrations.
Set up sessions, cookie cache strategy, and security/rate-limit options.
Add and configure Better Auth plugins plus corresponding client plugins.
Troubleshoot common Better Auth model, schema, and storage pitfalls.

Setup Workflow

Install: bun add 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 bun x @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

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).

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").

Hono, Cookies, And OAuth Provider Boundaries

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.

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

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

Agent Skills: Better Auth Integration Guide

Install this agent skill to your local

Skill Files