認証スキル

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

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

判断フロー

これは新規/空のプロジェクトですか?
├─ はい → 新規プロジェクトのセットアップ
│   1. フレームワークを特定する
│   2. データベースを選択する
│   3. better-auth をインストールする
│   4. auth.ts + auth-client.ts を作成する
│   5. ルートハンドラーをセットアップする
│   6. CLI migrate/generate を実行する
│   7. プラグインで機能を追加する
│
└─ いいえ → プロジェクトに既存の認証がありますか?
    ├─ はい → 移行/拡張
    │   • 現在の認証の不足部分を監査する
    │   • 段階的な移行を計画する
    │   • ドキュメント内の移行ガイドを参照する
    │
    └─ いいえ → 既存プロジェクトに認証を追加する
        1. プロジェクト構造を分析する
        2. better-auth をインストールする
        3. 認証設定を作成する
        4. ルートハンドラーを追加する
        5. スキーママイグレーションを実行する
        6. 既存ページに統合する

インストール

コア: 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文字以上、以下で生成: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<データベース接続文字列>

必要に応じて 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 - 有効期限、クッキーキャッシュ設定
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 サーバーコンポーネント: 認証設定に 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 による 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

プラグインパターン: サーバープラグイン + クライアントプラグイン + マイグレーション実行。

認証 UI の実装

サインインフロー:

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: true が有効
trustedOrigins が設定されている
レート制限が有効
メール確認が有効
パスワードリセットが実装されている
機密アプリケーションに 2FA がある
CSRF 保護が無効になっていない
account.accountLinking がレビュー済み

トラブルシューティング

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

リソース

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

create-auth-skill

SKILL.md 本文