OpenSkillIndex← back to search
claude-codedevelopment

Marketplace better-auth-best-practices

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.

install
source · Clone the upstream repo
git clone https://github.com/aiskillstore/marketplace
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/aiskillstore/marketplace "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/better-auth/better-auth-best-practices" ~/.claude/skills/aiskillstore-marketplace-better-auth-best-practices && rm -rf "$T"
manifest: skills/better-auth/better-auth-best-practices/SKILL.md
tags
#typescript#authentication#oauth#database#environment-variables#session-management
source content

Better Auth Integration Guide

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

Setup Workflow

  1. Install: 
    npm install better-auth
  2. Set env vars: 
    BETTER_AUTH_SECRET
    and 
    BETTER_AUTH_URL
  3. Create 
    auth.ts
    with database + config
  4. Create route handler for your framework
  5. Run 
    npx @better-auth/cli@latest migrate
  6. 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

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

  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

Resources