create-auth-skill by better-auth/skills
npx skills add https://github.com/better-auth/skills --skill create-auth-skill使用 Better Auth 为 TypeScript/JavaScript 应用程序添加身份验证的指南。
有关代码示例和语法,请参阅 better-auth.com/docs。
在编写任何代码之前,请通过扫描项目并向用户提出结构化问题来收集需求。这可以确保实施符合他们的需求。
分析代码库以自动检测:
next.config、svelte.config、nuxt.config、astro.config、vite.config 或 Express/Hono 入口文件。prisma/schema.prisma、drizzle.config、 依赖项(、、、、)。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
package.jsonpgmysql2better-sqlite3mongoosemongodbpackage.json 或导入中查找现有的身份验证库(next-auth、lucia、clerk、supabase/auth、firebase/auth)。pnpm-lock.yaml、yarn.lock、bun.lockb 或 package-lock.json。使用你的发现来预填默认值,并跳过你已经可以回答的问题。
使用 AskQuestion 工具在一次调用中向用户询问所有适用的问题。跳过任何你通过扫描已经确信有答案的问题。将它们分组在一个标题下,例如“身份验证设置规划”。
要询问的问题:
allow_multiple: trueallow_multiple: trueallow_multiple: trueallow_multiple: true收集答案后,以 Markdown 清单的形式呈现简洁的实施计划。例如:
## 身份验证实施计划
- **框架:** Next.js (App Router)
- **数据库:** PostgreSQL via Prisma
- **身份验证方法:** 邮箱/密码, Google OAuth, GitHub OAuth
- **插件:** 2FA, 组织, 邮箱验证
- **UI:** 自定义表单
### 步骤
1. 安装 `better-auth` 和 `@better-auth/cli`
2. 创建 `lib/auth.ts` 并配置服务器
3. 创建 `lib/auth-client.ts` 并配置 React 客户端
4. 在 `app/api/auth/[...all]/route.ts` 设置路由处理器
5. 配置 Prisma 适配器并生成模式
6. 添加 Google 和 GitHub OAuth 提供商
7. 启用 `twoFactor` 和 `organization` 插件
8. 设置邮箱验证处理器
9. 运行迁移
10. 创建登录 / 注册页面
在进入阶段 2 之前,请用户确认该计划。
只有在用户确认了阶段 1 的计划后,才继续此处。
根据上面收集的答案,遵循下面的决策树。
Is this a new/empty project?
├─ YES → 新项目设置
│ 1. 安装 better-auth (+ 根据计划安装作用域包)
│ 2. 创建包含所有规划配置的 auth.ts
│ 3. 创建包含框架客户端的 auth-client.ts
│ 4. 设置路由处理器
│ 5. 设置环境变量
│ 6. 运行 CLI 迁移/生成
│ 7. 根据计划添加插件
│ 8. 创建身份验证 UI 页面
│
├─ MIGRATING → 从现有身份验证迁移
│ 1. 审计当前身份验证的差距
│ 2. 规划增量迁移
│ 3. 在现有身份验证旁边安装 better-auth
│ 4. 迁移路由,然后是会话逻辑,最后是 UI
│ 5. 移除旧的身份验证库
│ 6. 查看文档中的迁移指南
│
└─ ADDING → 为现有项目添加身份验证
1. 分析项目结构
2. 安装 better-auth
3. 创建符合规划的身份验证配置
4. 添加路由处理器
5. 运行模式迁移
6. 集成到现有页面中
7. 添加计划的插件和功能
在实施结束时,彻底指导用户完成剩余的后续步骤(例如,设置 OAuth 应用凭据、部署环境变量、测试流程)。
核心: npm install better-auth
作用域包(根据需要):
| 包 | 用例 |
|---|---|
@better-auth/passkey | WebAuthn/通行密钥身份验证 |
@better-auth/sso | SAML/OIDC 企业级 SSO |
@better-auth/stripe | Stripe 支付 |
@better-auth/scim | SCIM 用户配置 |
@better-auth/expo | React Native/Expo |
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 等。
位置: 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
按框架导入:
| 框架 | 导入 |
|---|---|
| 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
| 框架 | 文件 | 处理器 |
|---|---|---|
| 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 服务器组件: 在身份验证配置中添加 nextCookies() 插件。
| 适配器 | 命令 |
|---|---|
| 内置 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 |
添加插件后重新运行。
| 数据库 | 设置 |
|---|---|
| SQLite | 直接传递 better-sqlite3 或 bun:sqlite 实例 |
| PostgreSQL | 直接传递 pg.Pool 实例 |
| MySQL | 直接传递 mysql2 连接池 |
| Prisma | prismaAdapter(prisma, { provider: "postgresql" }) 来自 better-auth/adapters/prisma |
| Drizzle | drizzleAdapter(db, { provider: "pg" }) 来自 better-auth/adapters/drizzle |
| MongoDB | mongodbAdapter(db) 来自 better-auth/adapters/mongodb |
| 插件 | 服务器导入 | 客户端导入 | 用途 |
|---|---|---|---|
twoFactor | better-auth/plugins | twoFactorClient | 使用 TOTP/OTP 的 2FA |
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 | - | 企业级 SSO |
插件模式: 服务器插件 + 客户端插件 + 运行迁移。
登录流程:
signIn.email({ email, password }) 或 signIn.social({ provider, callbackURL })error会话检查(客户端): useSession() 钩子返回 { data: session, isPending }
会话检查(服务器): auth.api.getSession({ headers: await headers() })
受保护路由: 检查会话,如果为 null 则重定向到 /sign-in。
BETTER_AUTH_SECRET 已设置 (32+ 字符)advanced.useSecureCookies: truetrustedOrigins 已配置account.accountLinking 已审查| 问题 | 修复方法 |
|---|---|
| "Secret not set" | 添加 BETTER_AUTH_SECRET 环境变量 |
| "Invalid Origin" | 将域名添加到 trustedOrigins |
| Cookie 未设置 | 检查 baseURL 是否与域名匹配;生产环境中启用安全 Cookie |
| OAuth 回调错误 | 在提供商仪表板中验证重定向 URI |
| 添加插件后出现类型错误 | 重新运行 CLI 生成/迁移 |
每周安装量
8.0K
代码仓库
GitHub 星标数
147
首次出现
2026年1月19日
安全审计
安装于
opencode6.0K
codex5.7K
gemini-cli5.6K
github-copilot5.6K
cursor4.9K
claude-code4.8K
Guide for adding authentication to TypeScript/JavaScript applications using Better Auth.
For code examples and syntax, seebetter-auth.com/docs.
Before writing any code, gather requirements by scanning the project and asking the user structured questions. This ensures the implementation matches their needs.
Analyze the codebase to auto-detect:
next.config, svelte.config, nuxt.config, astro.config, vite.config, or Express/Hono entry files.prisma/schema.prisma, drizzle.config, package.json deps (pg, mysql2, better-sqlite3, mongoose, mongodb).next-auth, lucia, clerk, supabase/auth, firebase/auth) in package.json or imports.pnpm-lock.yaml, yarn.lock, bun.lockb, or package-lock.json.Use what you find to pre-fill defaults and skip questions you can already answer.
Use the AskQuestion tool to ask the user all applicable questions in a single call. Skip any question you already have a confident answer for from the scan. Group them under a title like "Auth Setup Planning".
Questions to ask:
Project type (skip if detected)
Framework (skip if detected)
Database & ORM (skip if detected)
Authentication methods (always ask, allow multiple)
allow_multiple: trueSocial providers (only if they selected Social OAuth above — ask in a follow-up call)
allow_multiple: trueAfter collecting answers, present a concise implementation plan as a markdown checklist. Example:
## Auth Implementation Plan
- **Framework:** Next.js (App Router)
- **Database:** PostgreSQL via Prisma
- **Auth methods:** Email/password, Google OAuth, GitHub OAuth
- **Plugins:** 2FA, Organizations, Email verification
- **UI:** Custom forms
### Steps
1. Install `better-auth` and `@better-auth/cli`
2. Create `lib/auth.ts` with server config
3. Create `lib/auth-client.ts` with React client
4. Set up route handler at `app/api/auth/[...all]/route.ts`
5. Configure Prisma adapter and generate schema
6. Add Google & GitHub OAuth providers
7. Enable `twoFactor` and `organization` plugins
8. Set up email verification handler
9. Run migrations
10. Create sign-in / sign-up pages
Ask the user to confirm the plan before proceeding to Phase 2.
Only proceed here after the user confirms the plan from Phase 1.
Follow the decision tree below, guided by the answers collected above.
Is this a new/empty project?
├─ YES → New project setup
│ 1. Install better-auth (+ scoped packages per plan)
│ 2. Create auth.ts with all planned config
│ 3. Create auth-client.ts with framework client
│ 4. Set up route handler
│ 5. Set up environment variables
│ 6. Run CLI migrate/generate
│ 7. Add plugins from plan
│ 8. Create auth UI pages
│
├─ MIGRATING → Migration from existing auth
│ 1. Audit current auth for gaps
│ 2. Plan incremental migration
│ 3. Install better-auth alongside existing auth
│ 4. Migrate routes, then session logic, then UI
│ 5. Remove old auth library
│ 6. See migration guides in docs
│
└─ ADDING → Add auth to existing project
1. Analyze project structure
2. Install better-auth
3. Create auth config matching plan
4. Add route handler
5. Run schema migrations
6. Integrate into existing pages
7. Add planned plugins and features
At the end of implementation, guide users thoroughly on remaining next steps (e.g., setting up OAuth app credentials, deploying env vars, testing flows).
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 |
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.
Location: lib/auth.ts or src/lib/auth.ts
Minimal config needs:
database - Connection or adapteremailAndPassword: { enabled: true } - For email/password authStandard config adds:
socialProviders - OAuth providers (google, github, etc.)emailVerification.sendVerificationEmail - Email verification handleremailAndPassword.sendResetPassword - Password reset handlerFull config adds:
plugins - Array of feature pluginssession - Expiry, cookie cache settingsaccount.accountLinking - Multi-provider linkingrateLimit - Rate limiting configExport types: export type Session = typeof auth.$Infer.Session
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
| 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 |
Next.js Server Components: Add nextCookies() plugin to auth config.
| 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 |
Re-run after adding plugins.
| 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 |
| Plugin | Server Import | Client Import | Purpose |
|---|---|---|---|
twoFactor | better-auth/plugins | twoFactorClient | 2FA with TOTP/OTP |
organization | better-auth/plugins | organizationClient | Teams/orgs |
admin |
Plugin pattern: Server plugin + client plugin + run migrations.
Sign in flow:
signIn.email({ email, password }) or signIn.social({ provider, callbackURL })error in responseSession 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.
BETTER_AUTH_SECRET set (32+ chars)advanced.useSecureCookies: true in productiontrustedOrigins configuredaccount.accountLinking reviewed| 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 |
Weekly Installs
8.0K
Repository
GitHub Stars
147
First Seen
Jan 19, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode6.0K
codex5.7K
gemini-cli5.6K
github-copilot5.6K
cursor4.9K
claude-code4.8K
97,600 周安装
Email verification (only if Email & password was selected above — ask in a follow-up call)
Email provider (only if email verification is Yes, or if Password reset is selected in features — ask in a follow-up call)
Features & plugins (always ask, allow multiple)
allow_multiple: trueAuth pages (always ask, allow multiple — pre-select based on earlier answers)
allow_multiple: trueAuth UI style (always ask)
src/hooks.server.ts |
svelteKitHandler(auth) |
| SolidStart | Route file | solidStartHandler(auth) |
| Hono | Route file | auth.handler(c.req.raw) |
better-auth/adapters/drizzle| MongoDB | mongodbAdapter(db) from better-auth/adapters/mongodb |
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 |