better-auth-best-practices

Better Auth 統合ガイド

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

---

セットアップのワークフロー

1. インストールします：npm install better-auth
2. 環境変数を設定します：BETTER_AUTH_SECRET と BETTER_AUTH_URL
3. データベースと設定を含む auth.ts を作成します
4. 使用するフレームワークのルートハンドラーを作成します
5. npx @better-auth/cli@latest migrate を実行します
6. 確認します：GET /api/auth/ok を呼び出し、{ status: "ok" } が返されることを確認します

---

クイックリファレンス

環境変数

• 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 が定義されている場合 → セッションはそこに保存されます（データベースには保存されません）
2. session.storeSessionInDatabase: true を設定すると、データベースにも保存されます
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
• 初期化オプションのソース