Better Auth 統合ガイド

常に better-auth.com/docs でコード例と最新の API を確認してください。

Better Auth は TypeScript ファースト、フレームワーク非依存の認証フレームワークで、メール/パスワード、OAuth、マジックリンク、パスキー、およびプラグインを通じた多くの機能をサポートしています。

---

クイックリファレンス

環境変数

• BETTER_AUTH_SECRET - 暗号化シークレット(最小 32 文字)。生成方法: openssl rand -base64 32
• BETTER_AUTH_URL - ベース URL(例: https://example.com)

環境変数が設定されていない場合のみ、設定で baseURL/secret を定義します。

ファイル場所

CLI は auth.ts を次の場所で探します: ./, ./lib, ./utils, または ./src 配下。カスタムパスの場合は --config を使用します。

CLI コマンド

• npx @better-auth/cli@latest migrate - スキーマを適用(ビルトインアダプタ)
• npx @better-auth/cli@latest generate - Prisma/Drizzle 用スキーマを生成
• npx @better-auth/cli mcp --cursor - MCP を AI ツールに追加

プラグインの追加/変更後は再実行します。

---

コア設定オプション

オプション	説明
appName	オプション:表示名
baseURL	BETTER_AUTH_URL が設定されていない場合のみ
basePath	デフォルト /api/auth。ルートの場合は / に設定
secret	BETTER_AUTH_SECRET が設定されていない場合のみ
database	ほとんどの機能に必須。アダプタのドキュメントを参照
secondaryStorage	セッションとレート制限用の Redis/KV
emailAndPassword	{ enabled: true } で有効化
socialProviders	{ google: { clientId, clientSecret }, ... }
plugins	プラグインの配列
trustedOrigins	CSRF ホワイトリスト

---

データベース

直接接続: pg.Pool, mysql2 プール, better-sqlite3, または bun:sqlite インスタンスを渡します。

ORM アダプタ: better-auth/adapters/drizzle, better-auth/adapters/prisma, better-auth/adapters/mongodb からインポートします。

重要: Better Auth はアダプタのモデル名を使用します。基になるテーブル名ではありません。Prisma モデルが User でテーブルが users にマッピングされている場合、modelName: "user"(Prisma リファレンス)を使用します。"users" ではなく。

---

セッション管理

ストレージの優先順位:

1. secondaryStorage が定義されている場合 → セッションはそこに保存(DB ではない)
2. DB にも永続化するには session.storeSessionInDatabase: true を設定
3. データベースなし + cookieCache → 完全なステートレスモード

クッキーキャッシュ戦略:

• compact(デフォルト) - Base64url + HMAC。最小サイズ。
• jwt - 標準 JWT。読み取り可能だが署名済み。
• jwe - 暗号化。最大セキュリティ。

主なオプション: session.expiresIn(デフォルト 7 日間)、session.updateAge(更新間隔)、session.cookieCache.maxAge、session.cookieCache.version(すべてのセッションを無効化するために変更)。

---

ユーザーとアカウント設定

ユーザー: user.modelName, user.fields(カラムマッピング), user.additionalFields, user.changeEmail.enabled(デフォルトは無効), user.deleteUser.enabled(デフォルトは無効)。

アカウント: account.modelName, account.accountLinking.enabled, account.storeAccountCookie(ステートレス OAuth 用)。

登録に必須: email および name フィールド。

---

メールフロー

• emailVerification.sendVerificationEmail - 検証を機能させるには定義が必須
• emailVerification.sendOnSignUp / sendOnSignIn - 自動送信トリガー
• emailAndPassword.sendResetPassword - パスワードリセットメールハンドラー

---

セキュリティ

advanced 内:

• useSecureCookies - HTTPS クッキーを強制
• disableCSRFCheck - ⚠️ セキュリティリスク
• disableOriginCheck - ⚠️ セキュリティリスク
• crossSubDomainCookies.enabled - サブドメイン間でクッキーを共有
• ipAddress.ipAddressHeaders - プロキシ用カスタム IP ヘッダー
• database.generateId - カスタム ID 生成または "serial"/"uuid"/false

レート制限: rateLimit.enabled, rateLimit.window, rateLimit.max, rateLimit.storage("memory" | "database" | "secondary-storage")。

---

フック

エンドポイントフック: hooks.before / hooks.after - { matcher, handler } の配列。createAuthMiddleware を使用します。ctx.path, ctx.context.returned(after), ctx.context.session にアクセスできます。

データベースフック: databaseHooks.user.create.before/after, session および account も同様。デフォルト値の追加や作成後のアクションに便利です。

フックコンテキスト(ctx.context): session, secret, authCookies, password.hash()/verify(), adapter, internalAdapter, generateId(), tables, baseURL。

---

プラグイン

ツリーシェイキング用に専用パスからインポート:

import { twoFactor } from "better-auth/plugins/two-factor"

from "better-auth/plugins" ではなく。

人気のプラグイン: twoFactor, organization, passkey, magicLink, emailOtp, username, phoneNumber, admin, apiKey, bearer, jwt, multiSession, sso, oauthProvider, oidcProvider, openAPI, genericOAuth。

クライアントプラグインは createAuthClient({ plugins: [...] }) に入ります。

---

クライアント

以下からインポート: better-auth/client(vanilla), better-auth/react, better-auth/vue, better-auth/svelte, better-auth/solid。

主なメソッド: signUp.email(), signIn.email(), signIn.social(), signOut(), useSession(), getSession(), revokeSession(), revokeSessions()。

---

型安全性

型を推論: typeof auth.$Infer.Session, typeof auth.$Infer.Session.user。

クライアント/サーバープロジェクトが分離されている場合: createAuthClient<typeof auth>()。

---

よくある落とし穴

1. モデル名 vs テーブル名 - 設定は DB テーブル名ではなく ORM モデル名を使用
2. プラグインスキーマ - プラグイン追加後は CLI を再実行
3. セカンダリストレージ - デフォルトではセッションは DB ではなくそこに保存
4. クッキーキャッシュ - カスタムセッションフィールドはキャッシュされません。常に再取得
5. ステートレスモード - DB なし = セッションはクッキーのみ。キャッシュ有効期限でログアウト
6. メール変更フロー - まず現在のメールに送信してから、新しいメールに送信

---

リソース

• ドキュメント
• オプションリファレンス
• LLMs.txt
• GitHub
• 初期化オプションソース