create-auth-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Auth Skill

创建认证技能

Guide for adding authentication to TypeScript/JavaScript applications using Better Auth.

For code examples and syntax, see better-auth.com/docs.

本指南介绍如何在TypeScript/JavaScript应用中使用Better Auth添加身份认证功能。

如需代码示例和语法说明，请查看better-auth.com/docs。

Decision Tree

决策树

Is this a new/empty project?
├─ YES → New project setup
│   1. Identify framework
│   2. Choose database
│   3. Install better-auth
│   4. Create auth.ts + auth-client.ts
│   5. Set up route handler
│   6. Run CLI migrate/generate
│   7. Add features via plugins
│
└─ NO → Does project have existing auth?
    ├─ YES → Migration/enhancement
    │   • Audit current auth for gaps
    │   • Plan incremental migration
    │   • See migration guides in docs
    │
    └─ NO → Add auth to existing project
        1. Analyze project structure
        2. Install better-auth
        3. Create auth config
        4. Add route handler
        5. Run schema migrations
        6. Integrate into existing pages

这是一个新的/空项目吗？
├─ 是 → 新项目设置
│   1. 确定框架
│   2. 选择数据库
│   3. 安装better-auth
│   4. 创建auth.ts + auth-client.ts
│   5. 设置路由处理器
│   6. 运行CLI migrate/generate命令
│   7. 通过插件添加功能
│
└─ 否 → 项目已有认证功能？
    ├─ 是 → 迁移/增强
    │   • 审核当前认证方案的不足
    │   • 规划增量迁移方案
    │   • 查看文档中的迁移指南
    │
    └─ 否 → 为现有项目添加认证
        1. 分析项目结构
        2. 安装better-auth
        3. 创建认证配置
        4. 添加路由处理器
        5. 运行 schema 迁移
        6. 集成到现有页面中

Installation

安装

Core:

npm install better-auth

Scoped packages (as needed):

Package	Use case
`@better-auth/passkey`	WebAuthn/Passkey auth
`@better-auth/sso`	SAML/OIDC enterprise SSO
`@better-auth/stripe`	Stripe payments
`@better-auth/scim`	SCIM user provisioning
`@better-auth/expo`	React Native/Expo

核心包：

npm install better-auth

按需安装的作用域包：

包名	使用场景
`@better-auth/passkey`	WebAuthn/Passkey 认证
`@better-auth/sso`	SAML/OIDC 企业级单点登录
`@better-auth/stripe`	Stripe 支付集成
`@better-auth/scim`	SCIM 用户配置
`@better-auth/expo`	React Native/Expo 适配

Environment Variables

环境变量

env

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

Add OAuth secrets as needed:

GITHUB_CLIENT_ID

GITHUB_CLIENT_SECRET

GOOGLE_CLIENT_ID

, etc.

env

BETTER_AUTH_SECRET=<32位以上字符，可通过以下命令生成：openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<你的数据库连接字符串>

按需添加OAuth密钥：

GITHUB_CLIENT_ID

、

GITHUB_CLIENT_SECRET

、

GOOGLE_CLIENT_ID

等。

Server Config (auth.ts)

服务器配置（auth.ts）

Location:

lib/auth.ts

src/lib/auth.ts

Minimal config needs:

```
database
```
- Connection or adapter
```
emailAndPassword: { enabled: true }
```
- For email/password auth

Standard config adds:

```
socialProviders
```
- OAuth providers (google, github, etc.)
```
emailVerification.sendVerificationEmail
```
- Email verification handler
```
emailAndPassword.sendResetPassword
```
- Password reset handler

Full config adds:

```
plugins
```
- Array of feature plugins
```
session
```
- Expiry, cookie cache settings
```
account.accountLinking
```
- Multi-provider linking
```
rateLimit
```
- Rate limiting config

Export types:

export type Session = typeof auth.$Infer.Session

存放位置：

lib/auth.ts

或

src/lib/auth.ts

最小配置要求：

```
database
```
- 数据库连接或适配器
```
emailAndPassword: { enabled: true }
```
- 启用邮箱/密码认证

标准配置新增项：

```
socialProviders
```
- OAuth 提供商（google、github等）
```
emailVerification.sendVerificationEmail
```
- 邮箱验证处理器
```
emailAndPassword.sendResetPassword
```
- 密码重置处理器

完整配置新增项：

```
plugins
```
- 功能插件数组
```
session
```
- 过期时间、Cookie缓存设置
```
account.accountLinking
```
- 多提供商账号关联
```
rateLimit
```
- 限流配置

导出类型：

export type Session = typeof auth.$Infer.Session

Client Config (auth-client.ts)

客户端配置（auth-client.ts）

Import by framework:

Framework	Import
React/Next.js	`better-auth/react`
Vue	`better-auth/vue`
Svelte	`better-auth/svelte`
Solid	`better-auth/solid`
Vanilla JS	`better-auth/client`

Client plugins go in

createAuthClient({ plugins: [...] })

Common exports:

signIn

signUp

signOut

useSession

getSession

按框架导入：

框架	导入路径
React/Next.js	`better-auth/react`
Vue	`better-auth/vue`
Svelte	`better-auth/svelte`
Solid	`better-auth/solid`
Vanilla JS	`better-auth/client`

客户端插件需在

createAuthClient({ plugins: [...] })

中配置。

常用导出：

signIn

、

signUp

、

signOut

、

useSession

、

getSession

Route Handler Setup

路由处理器设置

Framework	File	Handler
Next.js App Router	`app/api/auth/[...all]/route.ts`	`toNextJsHandler(auth)` → export `{ GET, POST }`
Next.js Pages	`pages/api/auth/[...all].ts`	`toNextJsHandler(auth)` → default export
Express	Any file	`app.all("/api/auth/*", toNodeHandler(auth))`
SvelteKit	`src/hooks.server.ts`	`svelteKitHandler(auth)`
SolidStart	Route file	`solidStartHandler(auth)`
Hono	Route file	`auth.handler(c.req.raw)`

Next.js Server Components: Add

nextCookies()

plugin to auth config.

框架	文件路径	处理器
Next.js App Router	`app/api/auth/[...all]/route.ts`	`toNextJsHandler(auth)` → 导出 `{ GET, POST }`
Next.js Pages	`pages/api/auth/[...all].ts`	`toNextJsHandler(auth)` → 默认导出
Express	任意文件	`app.all("/api/auth/*", toNodeHandler(auth))`
SvelteKit	`src/hooks.server.ts`	`svelteKitHandler(auth)`
SolidStart	路由文件	`solidStartHandler(auth)`
Hono	路由文件	`auth.handler(c.req.raw)`

Next.js Server Components： 在认证配置中添加

nextCookies()

插件。

Database Migrations

数据库迁移

Adapter Command

Built-in Kysely

Adapter	Command
Built-in Kysely	`npx @better-auth/cli@latest migrate` (applies directly)
Prisma	`npx @better-auth/cli@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
Drizzle	`npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push`

npx @better-auth/cli@latest migrate

(applies directly)

Prisma

npx @better-auth/cli@latest generate --output prisma/schema.prisma

then

npx prisma migrate dev

Drizzle

npx @better-auth/cli@latest generate --output src/db/auth-schema.ts

then

npx drizzle-kit push

Re-run after adding plugins.

适配器命令

内置Kysely

适配器	命令
内置Kysely	`npx @better-auth/cli@latest migrate` （直接应用迁移）
Prisma	`npx @better-auth/cli@latest generate --output prisma/schema.prisma` 然后执行 `npx prisma migrate dev`
Drizzle	`npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` 然后执行 `npx drizzle-kit push`

npx @better-auth/cli@latest migrate

（直接应用迁移）

Prisma

npx @better-auth/cli@latest generate --output prisma/schema.prisma

然后执行

npx prisma migrate dev

Drizzle

npx @better-auth/cli@latest generate --output src/db/auth-schema.ts

然后执行

npx drizzle-kit push

添加插件后需重新运行上述命令。

Database Adapters

数据库适配器

Database	Setup
SQLite	Pass `better-sqlite3` or `bun:sqlite` instance directly
PostgreSQL	Pass `pg.Pool` instance directly
MySQL	Pass `mysql2` pool directly
Prisma	`prismaAdapter(prisma, { provider: "postgresql" })` from `better-auth/adapters/prisma`
Drizzle	`drizzleAdapter(db, { provider: "pg" })` from `better-auth/adapters/drizzle`
MongoDB	`mongodbAdapter(db)` from `better-auth/adapters/mongodb`

数据库	设置方式
SQLite	直接传入 `better-sqlite3` 或 `bun:sqlite` 实例
PostgreSQL	直接传入 `pg.Pool` 实例
MySQL	直接传入 `mysql2` 连接池
Prisma	从 `better-auth/adapters/prisma` 导入 `prismaAdapter(prisma, { provider: "postgresql" })`
Drizzle	从 `better-auth/adapters/drizzle` 导入 `drizzleAdapter(db, { provider: "pg" })`
MongoDB	从 `better-auth/adapters/mongodb` 导入 `mongodbAdapter(db)`

Common Plugins

常用插件

Plugin	Server Import	Client Import	Purpose
`twoFactor`	`better-auth/plugins`	`twoFactorClient`	2FA with TOTP/OTP
`organization`	`better-auth/plugins`	`organizationClient`	Teams/orgs
`admin`	`better-auth/plugins`	`adminClient`	User management
`bearer`	`better-auth/plugins`	-	API token auth
`openAPI`	`better-auth/plugins`	-	API docs
`passkey`	`@better-auth/passkey`	`passkeyClient`	WebAuthn
`sso`	`@better-auth/sso`	-	Enterprise SSO

Plugin pattern: Server plugin + client plugin + run migrations.

插件	服务端导入	客户端导入	用途
`twoFactor`	`better-auth/plugins`	`twoFactorClient`	基于TOTP/OTP的双因素认证
`organization`	`better-auth/plugins`	`organizationClient`	团队/组织管理
`admin`	`better-auth/plugins`	`adminClient`	用户管理
`bearer`	`better-auth/plugins`	-	API令牌认证
`openAPI`	`better-auth/plugins`	-	API文档生成
`passkey`	`@better-auth/passkey`	`passkeyClient`	WebAuthn认证
`sso`	`@better-auth/sso`	-	企业级单点登录

插件使用模式： 服务端插件 + 客户端插件 + 运行迁移。

Auth UI Implementation

认证UI实现

Sign in flow:

signIn.email({ email, password })

signIn.social({ provider, callbackURL })

Handle
```
error
```
in response
Redirect on success

Session check (client):

useSession()

hook returns

{ data: session, isPending }

Session check (server):

auth.api.getSession({ headers: await headers() })

Protected routes: Check session, redirect to

/sign-in

if null.

登录流程：

调用

signIn.email({ email, password })

或

signIn.social({ provider, callbackURL })

处理响应中的
```
error
```
成功后重定向

客户端会话检查：

useSession()

钩子返回

{ data: session, isPending }

服务端会话检查：

auth.api.getSession({ headers: await headers() })

受保护路由： 检查会话，若为空则重定向到

/sign-in

。

Security Checklist

安全检查清单

```
BETTER_AUTH_SECRET
```
set (32+ chars)
```
advanced.useSecureCookies: true
```
in production
```
trustedOrigins
```
configured
Rate limits enabled
Email verification enabled
Password reset implemented
2FA for sensitive apps
CSRF protection NOT disabled
```
account.accountLinking
```
reviewed

已设置
```
BETTER_AUTH_SECRET
```
（32位以上字符）
生产环境中启用
```
advanced.useSecureCookies: true
```
已配置
```
trustedOrigins
```
已启用限流
已启用邮箱验证
已实现密码重置功能
敏感应用已启用双因素认证
未禁用CSRF保护
已审核
```
account.accountLinking
```
配置

Troubleshooting

资源

Issue	Fix
"Secret not set"	Add `BETTER_AUTH_SECRET` env var
"Invalid Origin"	Add domain to `trustedOrigins`
Cookies not setting	Check `baseURL` matches domain; enable secure cookies in prod
OAuth callback errors	Verify redirect URIs in provider dashboard
Type errors after adding plugin	Re-run CLI generate/migrate

Resources

—