better-auth（Better Auth 认证）

Better Auth

Framework-agnostic TypeScript auth library. Plugin-based architecture, 40+ OAuth providers, 18+ framework integrations.

Quick Start

Install

npm install better-auth

Scoped packages (as needed):

Environment Variables

BETTER_AUTH_SECRET=<32+ chars, generate: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<connection string>

Server Config (lib/auth.ts)

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: process.env.DATABASE_URL,  // or adapter instance
  emailAndPassword: { enabled: true },
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
  plugins: [], // add plugins here
});

export type Session = typeof auth.$Infer.Session;

Client Config (lib/auth-client.ts)

import { createAuthClient } from "better-auth/react"; // or /vue, /svelte, /solid, /client

export const authClient = createAuthClient({
  plugins: [], // add client plugins here
});

Route Handler

See references/framework-integrations.md for all frameworks.

CLI Commands

npx @better-auth/cli@latest migrate          # Apply schema (built-in adapter)
npx @better-auth/cli@latest generate          # Generate for Prisma/Drizzle
npx @better-auth/cli@latest generate --output prisma/schema.prisma
npx @better-auth/cli@latest generate --output src/db/auth-schema.ts

Re-run after adding/changing plugins.

Core Concepts

• Server instance (auth): handles all auth logic, DB, sessions
• Client instance (authClient): framework-specific hooks (useSession, signIn, signUp, signOut)
• Plugins: extend both server and client — add endpoints, DB tables, hooks
• Type inference: auth.$Infer.Session, auth.$Infer.Session.user for full type safety
• For separate client/server projects: createAuthClient<typeof auth>()

Authentication Methods

Plugin Quick Reference

Import from dedicated paths for tree-shaking: import {twoFactor} from "better-auth/plugins/two-factor" NOT from "better-auth/plugins".

Pattern: server plugin in auth({plugins: [...]}) + client plugin in createAuthClient({plugins: [...]}) + re-run CLI migrations.

See references/plugins.md for detailed usage and custom plugin creation.

Database Setup

Critical: Config uses ORM model name, NOT DB table name. Prisma model User mapping to table users → use modelName: "user".

Core schema tables: user, session, account, verification. Plugins add their own tables.

See references/setup.md for full database setup details.

Session Management

Key options:

session: {
  expiresIn: 60 * 60 * 24 * 7,  // 7 days (default)
  updateAge: 60 * 60 * 24,       // refresh every 24h (default)
  freshAge: 60 * 60 * 24,        // require re-auth after 24h for sensitive ops
  cookieCache: {
    enabled: true,
    maxAge: 300,                  // 5 min
    strategy: "compact",          // "compact" | "jwt" | "jwe"
  },
}

• secondaryStorage (Redis/KV): sessions go there by default, not DB
• Stateless mode: no DB + cookieCache = session in cookie only
• customSession plugin: extend session with custom fields

See references/sessions.md for full session management details.

Security Checklist

See references/security.md for complete security hardening guide.

Common Gotchas

1. Model vs table name — config uses ORM model name, not DB table name
2. Plugin schema — re-run CLI after adding/changing plugins
3. Secondary storage — sessions go there by default, not DB. Set session.storeSessionInDatabase: true to persist both
4. Cookie cache — custom session fields NOT cached, always re-fetched from DB
5. Callback URLs — always use absolute URLs with origin (not relative paths)
6. Express v5 — use "/api/auth/*splat" not "/api/auth/*" for catch-all routes
7. Next.js RSC — add nextCookies() plugin to auth config for server component session access

Troubleshooting

Reference Index