Skill

Official

Pass

Audit score 90

better-auth-best-practices

better-auth/skills

Configure Better Auth server and client with database adapters, sessions, plugins, and environment variables for TypeScript authentication.

Source View on skills.sh

What is better-auth-best-practices?

Better Auth is a TypeScript authentication framework supporting email/password, OAuth, and plugins. Use this skill when setting up auth.ts, configuring database adapters, managing sessions, or adding authentication features like two-factor or magic links.

Set up Better Auth server with database adapters (Prisma, Drizzle, MongoDB, direct connections)
Configure email/password and OAuth authentication with social providers
Manage sessions with cookie caching strategies (compact, JWT, JWE) and secondary storage (Redis/KV)
Add plugins (two-factor, organization, passkey, magic link, email OTP, username, phone, API key, SSO, OIDC)
Handle environment variables (BETTER_AUTH_SECRET, BETTER_AUTH_URL) and security settings
Create route handlers and client integrations for vanilla, React, Vue, Svelte, or Solid

How to install better-auth-best-practices

npx skills add https://github.com/better-auth/skills --skill better-auth-best-practices

Prerequisites

Node.js and npm installed
Better Auth package: npm install better-auth
Environment variables set: BETTER_AUTH_SECRET (min 32 chars) and BETTER_AUTH_URL
Database setup (Postgres, MySQL, SQLite, MongoDB, or KV store)
Framework route handler setup (Next.js, SvelteKit, etc.)

Claude Code

Cursor

Windsurf

Cline

How to use better-auth-best-practices

1.Install Better Auth: npm install better-auth
2.Generate BETTER_AUTH_SECRET: openssl rand -base64 32 and set BETTER_AUTH_URL environment variable
3.Create auth.ts file in ./, ./lib, ./utils, or ./src with database config and options
4.Create a route handler for your framework pointing to Better Auth
5.Run npx @better-auth/cli@latest migrate to apply database schema
6.Verify setup by calling GET /api/auth/ok (should return {status: ok})
7.Add plugins if needed and re-run migrate command
8.Integrate client using createAuthClient from better-auth/react (or vanilla/vue/svelte/solid)

Use cases

Good for

Setting up a new TypeScript authentication system with email/password and OAuth providers
Migrating database schema and configuring ORM adapters (Prisma, Drizzle, MongoDB)
Adding multi-factor authentication, magic links, or passkey support via plugins
Configuring session management with Redis or KV storage for distributed systems
Implementing custom hooks for pre/post authentication actions or user creation logic

Who it's for

Full-stack TypeScript developers building authentication systems
Backend engineers configuring auth infrastructure with ORM adapters
Teams implementing OAuth, multi-factor, or advanced auth flows
Developers integrating Better Auth into Next.js, SvelteKit, or other frameworks

better-auth-best-practices FAQ

Where should I place the auth.ts file?

The CLI looks for auth.ts in: ./, ./lib, ./utils, or under ./src. Use --config flag for custom paths.

What's the difference between model name and table name in database config?

Better Auth config uses ORM model names (e.g., 'User' in Prisma), not database table names (e.g., 'users'). Use the model reference, not the table name.

Do sessions go to the database or secondary storage?

If secondaryStorage (Redis/KV) is defined, sessions go there by default. Set session.storeSessionInDatabase: true to also persist to DB. Without secondary storage, sessions use cookie cache.

How do I add plugins like two-factor or magic links?

Import from dedicated paths (e.g., import { twoFactor } from 'better-auth/plugins/two-factor'), add to plugins array in config, then re-run npx @better-auth/cli@latest migrate.

What cookie cache strategy should I use?

'compact' (default, smallest), 'jwt' (readable, signed), or 'jwe' (encrypted, most secure). Choose based on security needs and payload size.

Full instructions (SKILL.md)

Source of truth, from better-auth/skills.

name: better-auth-best-practices description: Configure Better Auth server and client, set up database adapters, manage sessions, add plugins, and handle environment variables. Use when users mention Better Auth, betterauth, auth.ts, or need to set up TypeScript authentication with email/password, OAuth, or plugin configuration.

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

Agent skill from better-auth/skills.

18k installs