Back to Details

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):
PackageUse 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
or 
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:
FrameworkImport
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

路由处理器设置

FrameworkFileHandler
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
ExpressAny file
app.all("/api/auth/*", toNodeHandler(auth))
SvelteKit
src/hooks.server.ts
svelteKitHandler(auth)
SolidStartRoute file
solidStartHandler(auth)
HonoRoute 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

数据库迁移

AdapterCommand
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
Re-run after adding plugins.
适配器命令
内置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
添加插件后需重新运行上述命令。

Database Adapters

数据库适配器

DatabaseSetup
SQLitePass 
better-sqlite3
or 
bun:sqlite
instance directly
PostgreSQLPass 
pg.Pool
instance directly
MySQLPass 
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

常用插件

PluginServer ImportClient ImportPurpose
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:
  1. signIn.email({ email, password })
    or 
    signIn.social({ provider, callbackURL })
  2. Handle 
    error
    in response
  3. 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.
登录流程：
  1. 调用
    signIn.email({ email, password })
    或
    signIn.social({ provider, callbackURL })
  2. 处理响应中的
    error
  3. 成功后重定向
客户端会话检查： 
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

资源

IssueFix
"Secret not set"Add 
BETTER_AUTH_SECRET
env var
"Invalid Origin"Add domain to 
trustedOrigins
Cookies not settingCheck 
baseURL
matches domain; enable secure cookies in prod
OAuth callback errorsVerify redirect URIs in provider dashboard
Type errors after adding pluginRe-run CLI generate/migrate

Resources

—
—