A TypeScript-first, framework-agnostic authentication framework with plugin support for email/password, OAuth, magic links, and more.

Which environment variables should I set?

Set BETTER_AUTH_SECRET (min 32 chars) and BETTER_AUTH_URL; if these aren’t defined, configure baseURL and secret in your config.

How do I apply migrations after changes to plugins?

Run migrate to apply the schema, then run generate to refresh Prisma/Drizzle adapters as needed; re-run after plugin updates.

better-auth-best-practices

Scanned

npx machina-cli add skill VictrixTech/agent-factory-template/better-auth-best-practices --openclaw

Files (1)

SKILL.md

6.0 KB

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.

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

Resources

Source

git clone https://github.com/VictrixTech/agent-factory-template/blob/main/.cursor/skills/better-auth-best-practices/SKILL.md

View on GitHub

Overview

This skill walks you through practical best practices for integrating Better Auth, a TypeScript-first, framework-agnostic authentication framework. It covers environment setup, file placement, core configuration, and robust session and security patterns to build scalable auth flows with plugins and adapters.

How This Skill Works

Better Auth is configured via env vars or a config file, with a CLI to migrate schemas and generate adapters for Prisma, Drizzle, or MongoDB. Place auth.ts in the project root (or common source folders) and use the CLI to apply schema changes and scaffold adapters after plugin changes. The system supports session storage choices, various cookie strategies, and plugin-driven extension points for email, OAuth, and more.

When to Use It

You’re building a TypeScript app that requires flexible authentication (email/password, OAuth, magic links, passkeys) via plugins.
You want framework-agnostic integration with adapters like Prisma, Drizzle, or MongoDB.
You need robust session management with options for Redis/secondary storage and multiple cookie strategies.
You plan to manage migrations and code generation through the Better Auth CLI after changes to plugins or schema.
You need to enforce secure defaults (CSRF, cookies, cross-subdomain sharing) and define clear email flows for verification and password reset.

Quick Start

Step 1: Set BETTER_AUTH_SECRET (min 32 chars) and BETTER_AUTH_URL, or configure baseURL/secret in your config when env vars are not defined.
Step 2: Run npx @better-auth/cli@latest migrate to apply the built-in schema (with your adapters).
Step 3: Run npx @better-auth/cli@latest generate to generate schema adapters for Prisma/Drizzle.

Best Practices

Define BETTER_AUTH_SECRET (min 32 chars) and BETTER_AUTH_URL, and only define baseURL/secret in config if env vars are not set.
Map models correctly to your ORM (use modelName like 'user' for Prisma, even if the table is 'users').
Enable and tailor session storage (secondaryStorage) and rate limiting to match your app scale.
Configure email flows (verification, on-sign-up, reset) to ensure reliable user onboarding and recovery.
Re-run migrate after adding or changing plugins and use generate to refresh your Prisma/Drizzle schemas.

Example Use Cases

Integrate Better Auth with Prisma by aligning user.modelName to 'user' and generating the Prisma schema after plugin changes.
Set BETTER_AUTH_SECRET and BETTER_AUTH_URL in the environment and let the config fallback to baseURL/secret when env vars are absent.
Enable email verification and password reset flows to activate end-to-end email-driven authentication.
Configure Redis as secondaryStorage to store sessions and apply rate limiting for high-traffic apps.
Run npx @better-auth/cli@latest migrate after plugin updates, then run generate to keep adapters in sync.

Frequently Asked Questions

Add this skill to your agents