前言¶
在 TypeScript 或 JavaScript 項目裏接入登錄、註冊和會話，往往需要同時處理數據庫適配器、框架路由、OAuth 回調、客戶端 SDK 和遷移腳本，文件多且步驟容易漏。Better Auth 本身把認證能力收斂到一套配置裏，但從零接線仍要對照文檔在多處改代碼。create-auth 是面向編碼助手的 Agent Skill，把「先摸清項目、再定方案、最後按框架落地」寫成固定流程，適合在新項目、存量項目或從其他認證庫遷移時使用。
這是什麼¶
create-auth 由 Better Auth 官方 skills 倉庫 提供，在 officialskills.sh 上歸類爲官方開發類 Skill。它的定位是：在 TS/JS 應用中用 Better Auth 腳手架化實現認證——自動識別框架與數據庫、配置適配器與路由處理器、接入 OAuth、並生成認證相關 UI 頁面。具體語法與 API 以 better-auth.com/docs 爲準。
核心功能¶
Skill 把工作拆成兩個階段，且 Phase 1 規劃必須在寫實現代碼之前完成。
項目掃描（自動推斷默認值）¶
助手會分析代碼庫，儘量從現有文件推斷：
- 框架：如
next.config、svelte.config、nuxt.config、astro.config、vite.config，或 Express / Hono 入口。 - 數據庫與 ORM：如
prisma/schema.prisma、drizzle.config.ts（含dialect）、package.json中的pg、postgres、mysql2、better-sqlite3、mongoose等依賴；Drizzle 驅動包可進一步區分 Postgres 接入方式。 - 已有認證：
package.json或 import 中的next-auth、lucia、clerk、supabase/auth、firebase/auth等。 - 包管理器：
pnpm-lock.yaml、yarn.lock、bun.lockb、package-lock.json。
能確定的項會用來預填選項，減少重複提問。
結構化規劃（AskQuestion）¶
在單次調用中儘量問完適用問題（已能從掃描得出的可跳過），標題可類似「Auth Setup Planning」。覆蓋範圍包括：
- 項目類型：全新項目 / 在現有項目加認證 / 從其他庫遷移
- 框架：Next.js（App 或 Pages Router）、SvelteKit、Nuxt、Astro、Express、Hono、SolidStart 等
- 數據庫與 ORM：PostgreSQL / MySQL / SQLite / MongoDB，配合 Prisma、Drizzle 或原生驅動
- 登錄方式（可多選）：郵箱密碼、社交 OAuth、Magic link、Passkey、手機號
- 社交提供商（選 OAuth 時追問）：Google、GitHub、Apple、Microsoft、Discord、Twitter/X
- 郵箱驗證（選郵箱密碼時）
- 發信方式（需要驗證或密碼重置時）：Resend 或暫時 Mock（console）
- 擴展能力（可多選）：2FA、組織/團隊、管理後臺、API Bearer Token、密碼重置等
- 需要的認證頁面：登錄、註冊，以及忘記密碼、重置密碼、郵箱驗證等（隨前面選項變化）
- 認證頁 UI 風格：極簡、居中卡片、分欄、玻璃擬態或自定義描述
回答彙總後，助手會輸出一份 Markdown 檢查清單式的 Auth Implementation Plan，並請用戶確認後再進入實現階段。
實現路徑（Phase 2）¶
用戶確認計劃後，按決策樹執行：
- 新項目：安裝
better-auth及計劃中的 scoped 包 →auth.ts/auth-client.ts→ 路由處理器 → 環境變量 → CLI migrate/generate → 插件與 UI 頁面。 - 遷移：審計現有認證、增量遷移、與舊庫並行安裝、先路由再會話再 UI、最後移除舊庫（文檔中有遷移指引）。
- 存量項目加認證：分析結構、安裝與配置、路由與 schema 遷移、接入現有頁面與插件。
實現結束後，Skill 要求引導用戶完成 OAuth 憑據、部署環境變量、端到端測試等後續步驟。
依賴與環境變量（實現時會用到）¶
核心包：
npm install better-auth
按需選用的 scoped 包示例：@better-auth/passkey、@better-auth/sso、@better-auth/stripe、@better-auth/scim、@better-auth/expo。
常見環境變量：
BETTER_AUTH_SECRET=<32+ chars, generate with: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<your database connection string>
OAuth 需額外配置如 GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GOOGLE_CLIENT_ID 等。
服務端配置通常放在 lib/auth.ts 或 src/lib/auth.ts，至少包含 database 與 emailAndPassword: { enabled: true }；標準場景還會配置 socialProviders、郵箱驗證與密碼重置回調等。計劃中提到的 schema 生成與遷移可通過 CLI（資料示例：npx auth@latest，auth 包隨 CLI 使用、無需全局安裝）配合框架路由（如 Next.js App Router 的 app/api/auth/[...all]/route.ts）完成。
安裝與啓用¶
在支持 Agent Skills 的助手中，可按 officialskills.sh 所列方式添加：
npx skills add https://github.com/better-auth/skills --skill better-auth-create-auth
也可直接向助手提供 Skill 目錄鏈接，請求安裝：
https://github.com/better-auth/skills/tree/main/better-auth/create-auth
安裝後，在對話中說明要爲項目增加登錄/註冊或遷移認證即可觸發該 Skill 的流程。Cursor、Codex CLI、Claude Code 等對 Skills 的安裝入口可能不同，但 Skill 本體均爲倉庫中的 SKILL.md 指令；未在官方頁面單獨列出的客戶端差異此處不展開。
典型用法¶
下列場景來自官方 Skill 頁面「When to use it」說明，對應用法是在已安裝 Skill 的會話裏用自然語言描述同類需求，由助手執行 Phase 1 掃描與提問，確認計劃後落地代碼。
- 在 Next.js App Router + Prisma 項目上增加郵箱密碼登錄。
- 在 SvelteKit 中配置 Google 與 GitHub OAuth。
- 從 NextAuth 或 Lucia 遷移到 Better Auth，儘量降低打斷。
- 在 Drizzle schema 上同時啓用 2FA、組織（organization） 等插件。
- 爲 Hono API 生成帶會話保護的登錄/註冊頁，並接好路由處理器。
規劃階段產出的計劃示例結構（框架、數據庫、登錄方式、插件、UI 步驟列表）與資料中的 checklist 一致；實現階段會按你選的框架生成 auth-client（如 React 客戶端）與對應 route handler。
適用場景與注意¶
適合：TypeScript/JavaScript 全棧或前後端分離項目；需要郵箱密碼、OAuth、2FA、組織等多能力組合；希望助手按倉庫約定一次性串起適配器、路由、遷移與頁面，而不是自己拼文檔片段。
注意：
- 必須先完成規劃並用戶確認，再寫實現，避免與項目棧不一致。
- 若項目已有其他認證庫，遷移路徑要求分步並行，勿在未審計前直接刪除舊依賴。
- Passkey、企業 SSO、Stripe、SCIM、Expo 等需額外 scoped 包，並在計劃中顯式選中。
- 郵件相關能力需配置真實發信（如 Resend）或接受開發期 Mock。
- 代碼細節以 Better Auth 官方文檔爲準；Skill 負責流程與決策樹，不替代閱讀 OAuth 提供商控制台與生產環境密鑰管理。
結尾¶
create-auth 把 Better Auth 接入拆成「掃描 → 一問一答式規劃 → 確認清單 → 分場景實現」，覆蓋多框架、多數據庫與從舊庫遷移。若你正在用 AI 編碼助手搭登錄體系，可從官方倉庫安裝 Skill，並在會話中直接描述目標棧與登錄方式。
官方地址：https://github.com/better-auth/skills/tree/main/better-auth/create-auth
