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

或使用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/):

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/下）：

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:

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

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

import { createAuthClient } from "better-auth/client";

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

创建

auth-client.ts

文件：

import { createAuthClient } from "better-auth/client";

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

Basic Usage

基础使用示例

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

// 注册
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

特性选择矩阵

Feature	Plugin Required	Use Case	Reference
Email/Password	No (built-in)	Basic auth	email-password-auth.md
OAuth (GitHub, Google, etc.)	No (built-in)	Social login	oauth-providers.md
Email Verification	No (built-in)	Verify email addresses	email-password-auth.md
Password Reset	No (built-in)	Forgot password flow	email-password-auth.md
Two-Factor Auth (2FA/TOTP)	Yes ( `twoFactor` )	Enhanced security	advanced-features.md
Passkeys/WebAuthn	Yes ( `passkey` )	Passwordless auth	advanced-features.md
Magic Link	Yes ( `magicLink` )	Email-based login	advanced-features.md
Username Auth	Yes ( `username` )	Username login	email-password-auth.md
Organizations/Multi-tenant	Yes ( `organization` )	Team/org features	advanced-features.md
Rate Limiting	No (built-in)	Prevent abuse	advanced-features.md
Session Management	No (built-in)	User sessions	advanced-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:

Server (
```
better-auth
```
): Handles auth logic, database ops, API routes
Client (
```
better-auth/client
```
): Provides hooks/methods for frontend
Plugins: Extend both server/client functionality

Better Auth 采用客户端-服务器架构：

服务器端 (
```
better-auth
```
)：处理认证逻辑、数据库操作、API路由
客户端 (
```
better-auth/client
```
)：为前端提供钩子函数与方法
插件：扩展服务器端与客户端的功能

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
```
包
设置环境变量（密钥、服务地址）
创建认证服务器实例并配置数据库
运行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

资源

Docs: https://www.better-auth.com/docs
GitHub: https://github.com/better-auth/better-auth
Plugins: https://www.better-auth.com/docs/plugins
Examples: https://www.better-auth.com/docs/examples

官方文档：https://www.better-auth.com/docs
GitHub仓库：https://github.com/better-auth/better-auth
插件市场：https://www.better-auth.com/docs/plugins
示例项目：https://www.better-auth.com/docs/examples