Terminal
Terminal/Skill
Guide for setting up Better Auth on the server and client, including database adapters, sessions, plugins and environment variables.
By Better Auth
Works with
npx skills add better-auth/skills --skill better-auth-best-practicesUse documentation that matches the Better Auth version installed in the project. APIs and plugin names can differ across maintained release lines.
better-auth version in the lockfile, falling back to the package manifest when no lockfile is available.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.When planning an upgrade, separate guidance for the currently installed version from guidance for the target version.
npm install better-authBETTER_AUTH_SECRET and BETTER_AUTH_URLauth.ts with database + confignpx auth@latest migratenpx auth@latest generate --output src/db/auth-schema.ts then npx drizzle-kit push (dev) or npx drizzle-kit generate && npx drizzle-kit migrate (prod)npx auth@latest generate --output prisma/schema.prisma then npx prisma migrate devGET /api/auth/ok — should return { status: "ok" }BETTER_AUTH_SECRET - Encryption secret (min 32 chars). Generate: openssl rand -base64 32BETTER_AUTH_URL - Base URL (e.g., https://example.com)Only define baseURL/secret in config if env vars are NOT set.
CLI looks for auth.ts in: ./, ./lib, ./utils, or under ./src. Use --config for custom path.
npx auth@latest migrate - Apply schema (built-in adapter)npx auth@latest generate - Generate schema for Prisma/Drizzlenpx auth@latest mcp --cursor - Add MCP to AI toolsRe-run after adding/changing plugins.
| 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 |
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".
Storage priority:
secondaryStorage defined → sessions go there (not DB)session.storeSessionInDatabase: true to also persist to DBcookieCache → fully stateless modeCookie 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: 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.
emailVerification.sendVerificationEmail - Must be defined for verification to workemailVerification.sendOnSignUp / sendOnSignIn - Auto-send triggersemailAndPassword.sendResetPassword - Password reset email handlerIn advanced:
useSecureCookies - Force HTTPS cookiesdisableCSRFCheck - ⚠️ Security riskdisableOriginCheck - ⚠️ Security riskcrossSubDomainCookies.enabled - Share cookies across subdomainsipAddress.ipAddressHeaders - Custom IP headers for proxiesdatabase.generateId - Custom ID generation or "serial"/"uuid"/falseRate limiting: rateLimit.enabled, rateLimit.window, rateLimit.max, rateLimit.storage ("memory" | "database" | "secondary-storage").
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.
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: [...] }).
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().
Infer types: typeof auth.$Infer.Session, typeof auth.$Infer.Session.user.
For separate client/server projects: createAuthClient<typeof auth>().
drizzleAdapter(db, ...) requires a db instance from drizzle(). See create-auth skill for setup examples (node-postgres, postgres.js, Neon).drizzle-kit commands require a drizzle.config.ts pointing to the generated schema file and DB credentials.