better-auth-best-practices

Better Auth 統合ガイド

コード例と最新の API については、必ず better-auth.com/docs を参照してください。

Better Auth は TypeScript を第一に考えた、フレームワークに依存しない認証フレームワークです。プラグインを通じて、メールアドレスとパスワード、OAuth、マジックリンク、パスキーなどに対応しています。

---

クイックリファレンス

環境変数

• BETTER_AUTH_SECRET - 暗号化シークレット（最小 32 文字）。生成コマンド：openssl rand -base64 32
• BETTER_AUTH_URL - ベース URL（例：https://example.com）

環境変数が設定されていない場合に限り、設定で baseURL／secret を定義してください。

ファイルの場所

CLI は ./、./lib、./utils、または ./src 以下にある auth.ts を検索します。カスタムパスを指定するには --config を使用してください。

CLI コマンド

• npx @better-auth/cli@latest migrate - スキーマを適用します（組み込みアダプター）
• npx @better-auth/cli@latest generate - Prisma／Drizzle 用のスキーマを生成します
• npx @better-auth/cli mcp --cursor - AI ツールに MCP を追加します

プラグインを追加・変更した後は、再実行してください。

---

コア設定オプション

オプション	備考
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 のモデルが users テーブルにマッピングされる User の場合、"users" ではなく（Prisma の参照名である）modelName: "user" を使用してください。

---

セッション管理

保存先の優先順位：

1. secondaryStorage が定義されている場合 → セッションはそこに保存されます（DB には保存されません）
2. session.storeSessionInDatabase: true を設定すると、DB にも保存されます
3. データベースがなく、cookieCache がある場合 → 完全なステートレスモードになります

Cookie キャッシュ戦略：

• 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 Cookie を強制します
• disableCSRFCheck - ⚠️ セキュリティリスクがあります
• disableOriginCheck - ⚠️ セキュリティリスクがあります
• crossSubDomainCookies.enabled - サブドメイン間で Cookie を共有します
• 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（バニラ）、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. モデル名とテーブル名 - 設定では DB のテーブル名ではなく、ORM のモデル名を使用します
2. プラグインのスキーマ - プラグインの追加後、CLI を再実行します
3. セカンダリストレージ - セッションはデフォルトで DB ではなく、セカンダリストレージに保存されます
4. Cookie キャッシュ - カスタムのセッションフィールドはキャッシュされず、常に再取得されます
5. ステートレスモード - DB がない場合、セッションは Cookie のみに保存され、キャッシュの有効期限が切れるとログアウトします
6. メールアドレス変更フロー - まず現在のメールアドレスに送信し、その後、新しいメールアドレスに送信します

---

リソース

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