Back to Details

better-auth

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Better Auth Skill

Better Auth技能

Better Auth is comprehensive, framework-agnostic authentication/authorization framework for TypeScript with built-in email/password, social OAuth, and powerful plugin ecosystem for advanced features.
Better Auth是一个全面的、与框架无关的TypeScript认证/授权框架，内置邮箱/密码、社交OAuth功能，并有强大的插件生态系统用于扩展高级功能。

When to Use

使用场景

  • Implementing auth in TypeScript/JavaScript applications
  • Adding email/password or social OAuth authentication
  • Setting up 2FA, passkeys, magic links, advanced auth features
  • Building multi-tenant apps with organization support
  • Managing sessions and user lifecycle
  • Working with any framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Hono, Express, etc.)
  • 在TypeScript/JavaScript应用中实现认证
  • 添加邮箱/密码或社交OAuth认证
  • 设置2FA、Passkeys、魔法链接等高级认证功能
  • 构建支持组织的多租户应用
  • 管理会话和用户生命周期
  • 适用于任何框架（Next.js、Nuxt、SvelteKit、Remix、Astro、Hono、Express等）

Quick Start

快速开始

Installation

安装

bash
npm install better-auth
bash
npm install better-auth

or pnpm/yarn/bun add better-auth

or pnpm/yarn/bun add better-auth

undefined
undefined

Environment Setup

环境配置

Create 
.env
:
env
BETTER_AUTH_SECRET=<generated-secret-32-chars-min>
BETTER_AUTH_URL=http://localhost:3000
创建
.env
文件：
env
BETTER_AUTH_SECRET=<生成的32位以上密钥>
BETTER_AUTH_URL=http://localhost:3000

Basic Server Setup

基础服务器配置

Create 
auth.ts
(root, lib/, utils/, or under src/app/server/):
ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: {
    // See references/database-integration.md
  },
  emailAndPassword: {
    enabled: true,
    autoSignIn: true
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }
  }
});
创建
auth.ts
（可放在根目录、lib/、utils/或src/app/server/下）：
ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: {
    // 参考references/database-integration.md
  },
  emailAndPassword: {
    enabled: true,
    autoSignIn: true
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }
  }
});

Database Schema

数据库 Schema

bash
npx @better-auth/cli generate  # Generate schema/migrations
npx @better-auth/cli migrate   # Apply migrations (Kysely only)
bash
npx @better-auth/cli generate  # 生成Schema/迁移文件
npx @better-auth/cli migrate   # 应用迁移（仅支持Kysely）

Mount API Handler

挂载API处理器

Next.js App Router:
ts
// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);
Other frameworks: See references/email-password-auth.md#framework-setup
Next.js App Router：
ts
// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);
其他框架： 参考references/email-password-auth.md#framework-setup

Client Setup

客户端配置

Create 
auth-client.ts
:
ts
import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"
});
创建
auth-client.ts
：
ts
import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"
});

Basic Usage

基础使用

ts
// Sign up
await authClient.signUp.email({
  email: "user@example.com",
  password: "secure123",
  name: "John Doe"
});

// Sign in
await authClient.signIn.email({
  email: "user@example.com",
  password: "secure123"
});

// OAuth
await authClient.signIn.social({ provider: "github" });

// Session
const { data: session } = authClient.useSession(); // React/Vue/Svelte
const { data: session } = await authClient.getSession(); // Vanilla JS
ts
// 注册
await authClient.signUp.email({
  email: "user@example.com",
  password: "secure123",
  name: "John Doe"
});

// 登录
await authClient.signIn.email({
  email: "user@example.com",
  password: "secure123"
});

// OAuth登录
await authClient.signIn.social({ provider: "github" });

// 会话
const { data: session } = authClient.useSession(); // React/Vue/Svelte
const { data: session } = await authClient.getSession(); // 原生JS

Feature Selection Matrix

功能选择矩阵

FeaturePlugin RequiredUse CaseReference
Email/PasswordNo (built-in)Basic authemail-password-auth.md
OAuth (GitHub, Google, etc.)No (built-in)Social loginoauth-providers.md
Email VerificationNo (built-in)Verify email addressesemail-password-auth.md
Password ResetNo (built-in)Forgot password flowemail-password-auth.md
Two-Factor Auth (2FA/TOTP)Yes (
twoFactor
)		Enhanced securityadvanced-features.md
Passkeys/WebAuthnYes (
passkey
)		Passwordless authadvanced-features.md
Magic LinkYes (
magicLink
)		Email-based loginadvanced-features.md
Username AuthYes (
username
)		Username loginemail-password-auth.md
Organizations/Multi-tenantYes (
organization
)		Team/org featuresadvanced-features.md
Rate LimitingNo (built-in)Prevent abuseadvanced-features.md
Session ManagementNo (built-in)User sessionsadvanced-features.md
功能是否需要插件使用场景参考文档
邮箱/密码认证否（内置）基础认证email-password-auth.md
OAuth（GitHub、Google等）否（内置）社交登录oauth-providers.md
邮箱验证否（内置）验证邮箱地址email-password-auth.md
密码重置否（内置）忘记密码流程email-password-auth.md
双因素认证（2FA/TOTP）是（
twoFactor
插件）		增强安全性advanced-features.md
Passkeys/WebAuthn是（
passkey
插件）		无密码认证advanced-features.md
魔法链接是（
magicLink
插件）		基于邮箱的登录advanced-features.md
用户名认证是（
username
插件）		用户名登录email-password-auth.md
组织/多租户是（
organization
插件）		团队/组织功能advanced-features.md
速率限制否（内置）防止滥用advanced-features.md
会话管理否（内置）用户会话管理advanced-features.md

Auth Method Selection Guide

认证方式选择指南

Choose Email/Password when:
  • Building standard web app with traditional auth
  • Need full control over user credentials
  • Targeting users who prefer email-based accounts
Choose OAuth when:
  • Want quick signup with minimal friction
  • Users already have social accounts
  • Need access to social profile data
Choose Passkeys when:
  • Want passwordless experience
  • Targeting modern browsers/devices
  • Security is top priority
Choose Magic Link when:
  • Want passwordless without WebAuthn complexity
  • Targeting email-first users
  • Need temporary access links
Combine Multiple Methods when:
  • Want flexibility for different user preferences
  • Building enterprise apps with various auth requirements
  • Need progressive enhancement (start simple, add more options)
选择邮箱/密码认证的场景：
  • 构建使用传统认证方式的标准Web应用
  • 需要完全控制用户凭证
  • 面向偏好基于邮箱的账户的用户
选择OAuth的场景：
  • 希望实现快速注册，减少用户操作
  • 用户已拥有社交账户
  • 需要访问社交资料数据
选择Passkeys的场景：
  • 希望实现无密码体验
  • 面向现代浏览器/设备
  • 安全性是首要考虑因素
选择魔法链接的场景：
  • 希望实现无密码体验，且不想处理WebAuthn的复杂度
  • 面向优先使用邮箱的用户
  • 需要临时访问链接
组合多种方式的场景：
  • 希望为不同用户偏好提供灵活性
  • 构建具有多种认证需求的企业应用
  • 需要渐进式增强（从简单开始，逐步添加更多选项）

Core Architecture

核心架构

Better Auth uses client-server architecture:
  1. Server (
    better-auth
    ): Handles auth logic, database ops, API routes
  2. Client (
    better-auth/client
    ): Provides hooks/methods for frontend
  3. Plugins: Extend both server/client functionality
Better Auth采用客户端-服务器架构：
  1. 服务器（
    better-auth
    ）：处理认证逻辑、数据库操作、API路由
  2. 客户端（
    better-auth/client
    ）：为前端提供钩子/方法
  3. 插件：扩展服务器和客户端的功能

Implementation Checklist

实现检查清单

  • Install 
    better-auth
    package
  • Set environment variables (SECRET, URL)
  • Create auth server instance with database config
  • Run schema migration (
    npx @better-auth/cli generate
    )
  • Mount API handler in framework
  • Create client instance
  • Implement sign-up/sign-in UI
  • Add session management to components
  • Set up protected routes/middleware
  • Add plugins as needed (regenerate schema after)
  • Test complete auth flow
  • Configure email sending (verification/reset)
  • Enable rate limiting for production
  • Set up error handling
  • 安装
    better-auth
    包
  • 设置环境变量（SECRET、URL）
  • 创建带数据库配置的认证服务器实例
  • 运行Schema迁移（
    npx @better-auth/cli generate
    ）
  • 在框架中挂载API处理器
  • 创建客户端实例
  • 实现注册/登录UI
  • 为组件添加会话管理
  • 设置受保护的路由/中间件
  • 根据需要添加插件（添加后重新生成Schema）
  • 测试完整的认证流程
  • 配置邮件发送（验证/重置）
  • 为生产环境启用速率限制
  • 设置错误处理

Reference Documentation

参考文档

Core Authentication

核心认证

  • Email/Password Authentication - Email/password setup, verification, password reset, username auth
  • OAuth Providers - Social login setup, provider configuration, token management
  • Database Integration - Database adapters, schema setup, migrations
  • 邮箱/密码认证 - 邮箱/密码设置、验证、密码重置、用户名认证
  • OAuth提供商 - 社交登录设置、提供商配置、令牌管理
  • 数据库集成 - 数据库适配器、Schema设置、迁移

Advanced Features

高级功能

  • Advanced Features - 2FA/MFA, passkeys, magic links, organizations, rate limiting, session management
  • 高级功能 - 2FA/MFA、Passkeys、魔法链接、组织、速率限制、会话管理

Scripts

脚本

  • scripts/better_auth_init.py
    - Initialize Better Auth configuration with interactive setup
  • scripts/better_auth_init.py
    - 通过交互式设置初始化Better Auth配置

Resources

资源