create-auth-skill

認証スキルの作成

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

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

---

フェーズ 1：計画（実装前に必須）

コードを書く前に、プロジェクトをスキャンし、構造化された質問をユーザーに尋ねて要件を集めます。これにより、実装がニーズに合ったものになります。

ステップ 1：プロジェクトをスキャンする

コードベースを分析して、次の項目を自動検出します。

• フレームワーク — next.config、svelte.config、nuxt.config、astro.config、vite.config、または Express／Hono のエントリーファイルを探します。
• データベース／ORM — prisma/schema.prisma、drizzle.config、package.json の依存関係（pg、mysql2、better-sqlite3、mongoose、mongodb）を探します。
• 既存の認証 — package.json またはインポート内で既存の認証ライブラリ（next-auth、lucia、clerk、supabase/auth、firebase/auth）を探します。
• パッケージマネージャー — pnpm-lock.yaml、yarn.lock、bun.lockb、または package-lock.json を確認します。

見つかった情報を使ってデフォルト値を事前入力し、すでに答えが分かっている質問は省略します。

ステップ 2：プランニングに関する質問をする

AskQuestion ツールを使って、該当するすべての質問を1 回の呼び出しでユーザーに尋ねます。スキャン結果からすでに確実な回答が得られている質問は省略します。「認証設定のプランニング」のようなタイトルの下に質問をまとめます。

質問する項目：

1. プロジェクトの種類（検出済みの場合は省略）

   • プロンプト：「これはどの種類のプロジェクトですか？」
   • 選択肢：ゼロから新しいプロジェクトを作成 | 既存のプロジェクトに認証を追加 | 別の認証ライブラリから移行

2. フレームワーク（検出済みの場合は省略）

   • プロンプト：「使用しているフレームワークはどれですか？」
   • 選択肢：Next.js (App Router) | Next.js (Pages Router) | SvelteKit | Nuxt | Astro | Express | Hono | SolidStart | その他

3. データベースと ORM（検出済みの場合は省略）

   • プロンプト：「使用するデータベース構成はどれですか？」
   • 選択肢：PostgreSQL (Prisma) | PostgreSQL (Drizzle) | PostgreSQL (pg driver) | MySQL (Prisma) | MySQL (Drizzle) | MySQL (mysql2 driver) | SQLite (Prisma) | SQLite (Drizzle) | SQLite (better-sqlite3 driver) | MongoDB (Mongoose) | MongoDB (native driver)

4. 認証方法（必ず尋ね、複数選択を許可）

   • プロンプト：「必要なサインイン方法はどれですか？」
   • 選択肢：メールアドレスとパスワード | ソーシャル OAuth（Google、GitHub など） | マジックリンク（パスワード不要のメール認証） | パスキー（WebAuthn） | 電話番号
   • allow_multiple: true

5. ソーシャルプロバイダー（上記でソーシャル OAuth を選択した場合のみ、後続の呼び出しで尋ねる）

   • プロンプト：「必要なソーシャルプロバイダーはどれですか？」
   • 選択肢：Google | GitHub | Apple | Microsoft | Discord | Twitter/X
   • allow_multiple: true

6. メールアドレスの確認（上記でメールアドレスとパスワードを選択した場合のみ、後続の呼び出しで尋ねる）

   • プロンプト：「メールアドレスの確認を必須にしますか？」
   • 選択肢：はい | いいえ

7. メールプロバイダー（メールアドレスの確認が「はい」の場合、または機能でパスワードリセットを選択した場合のみ、後続の呼び出しで尋ねる）

   • プロンプト：「メールをどのように送信しますか？」
   • 選択肢：Resend | 今はモックにする（console.log）

8. 機能とプラグイン（必ず尋ね、複数選択を許可）

   • プロンプト：「追加で必要な機能はどれですか？」
   • 選択肢：二要素認証（2FA） | 組織／チーム | 管理者ダッシュボード | API ベアラートークン | パスワードリセット | 該当なし
   • allow_multiple: true

9. 認証ページ（必ず尋ね、複数選択を許可。前の回答に基づいて事前選択する）

   • プロンプト：「必要な認証ページはどれですか？」
   • 選択肢は前の回答に応じて変わります：
     • 常に選択可能：サインイン | サインアップ
     • メールアドレスとパスワードを選択した場合：パスワードを忘れた場合 | パスワードのリセット
     • メールアドレスの確認を有効にした場合：メールアドレスの確認
   • allow_multiple: true

10. 認証 UI のスタイル（必ず尋ねる）

• プロンプト：「認証ページのスタイルはどれがよいですか？1 つ選ぶか、独自のスタイルを説明してください。」
• 選択肢：ミニマルでシンプル | 背景付きの中央配置カード | 分割レイアウト（フォーム＋ヒーロー画像） | フローティング／グラスモーフィズム | その他（説明してください）

ステップ 3：プランをまとめる

回答を集めたら、Markdown のチェックリストで実装プランを簡潔に提示します。例：

## 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

フェーズ 2 に進む前に、プランを確認するようユーザーに依頼します。

---

フェーズ 2：実装

フェーズ 1 のプランをユーザーが確認した後にのみ、ここに進みます。

以下の判断ツリーに従い、上記で集めた回答を参考にします。

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

実装の最後に、残りの次のステップ（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+ 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 が設定されている
• レート制限が有効になっている
• メール認証が有効になっている
• パスワードリセットが実装されている
• 機密性の高いアプリでは 2FA が設定されている
• CSRF 保護が無効になっていない
• account.accountLinking が確認されている

---

トラブルシューティング

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

---

リソース

• ドキュメント
• サンプル
• プラグイン
• CLI
• 移行ガイド