create-auth-skill

認証スキルの作成

Better Auth を使用して TypeScript／JavaScript アプリケーションに認証を追加するためのガイドです。

コード例と構文については、better-auth.com/docs をご覧ください。

---

意思決定ツリー

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

---

インストール

コア： npm install better-auth

スコープ付きパッケージ（必要に応じて）：

パッケージ	使用例
@better-auth/passkey	WebAuthn／Passkey 認証
@better-auth/sso	SAML／OIDC エンタープライズ SSO
@better-auth/stripe	Stripe 決済
@better-auth/scim	SCIM ユーザープロビジョニング
@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>

必要に応じて OAuth シークレットを追加します：GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GOOGLE_CLIENT_ID など。

---

サーバー設定（auth.ts）

配置場所： 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

---

クライアント設定（auth-client.ts）

フレームワーク別のインポート：

フレームワーク	インポート
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 Server Components： auth 設定に 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	better-auth/adapters/prisma の prismaAdapter(prisma, { provider: "postgresql" })
Drizzle	better-auth/adapters/drizzle の drizzleAdapter(db, { provider: "pg" })
MongoDB	better-auth/adapters/mongodb の mongodbAdapter(db)

---

一般的なプラグイン

プラグイン	サーバーのインポート	クライアントのインポート	用途
twoFactor	better-auth/plugins	twoFactorClient	TOTP/OTP による 2 要素認証
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

プラグインのパターン： サーバープラグインとクライアントプラグインを追加し、マイグレーションを実行します。

---

認証 UI の実装

サインインのフロー：

1. signIn.email({ email, password }) または signIn.social({ provider, callbackURL }) を実行します
2. レスポンスの error を処理します
3. 成功したらリダイレクトします

セッションの確認（クライアント）： useSession() フックは { data: session, isPending } を返します

セッションの確認（サーバー）： auth.api.getSession({ headers: await headers() })

保護されたルート： セッションを確認し、null の場合は /sign-in にリダイレクトします。

---

セキュリティチェックリスト

• BETTER_AUTH_SECRET が設定されている（32 文字以上）
• 本番環境で advanced.useSecureCookies: true が設定されている
• trustedOrigins が設定されている
• レート制限が有効になっている
• メール認証が有効になっている
• パスワードリセットが実装されている
• 機密性の高いアプリでは 2 要素認証を使用している
• CSRF 保護が無効化されていない
• account.accountLinking を確認している

---

トラブルシューティング

問題	解決方法
"Secret not set"	BETTER_AUTH_SECRET 環境変数を追加します
"Invalid Origin"	ドメインを trustedOrigins に追加します
Cookie が設定されない	baseURL がドメインと一致しているか確認し、本番環境でセキュア Cookie を有効にします
OAuth コールバックエラー	プロバイダーダッシュボードでリダイレクト URI を確認します
プラグイン追加後の型エラー	CLI の generate/migrate を再実行します

---

リソース

• ドキュメント
• サンプル
• プラグイン
• CLI
• マイグレーションガイド