better-auth-best-practices

Better Auth 統合ガイド

リファレンスリポジトリ

• Better Auth — プラグインを備えた TypeScript 認証フレームワーク

上流情報の確認

Better Auth の API シグネチャ、アダプターの動作、生成されるスキーマ、プラグインのオプション、セッションの保存先、Cookie の動作、セキュリティのデフォルト設定が正確性に影響する場合は、記憶に頼る前に better-auth/better-auth を対象として DeepWiki に絞った質問をしてください。まず情報を把握し、コードを変更する前に、決定的な詳細をローカルにインストールされた型、ソースコード、または公式ドキュメントで確認してください。

以下で説明する、変更の少ない基本的なセットアップについては、DeepWiki を使う必要はありません。

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

このスキルを使用する場合

次のような場合に、このパターンを使用してください。

• TypeScript プロジェクトで Better Auth のサーバー／クライアントのセットアップを構成する。
• 環境変数、データベースアダプター、CLI マイグレーションを連携させる。
• セッション、Cookie キャッシュ戦略、セキュリティ／レート制限オプションを設定する。
• Better Auth プラグインと、対応するクライアントプラグインを追加・構成する。
• Better Auth のモデル、スキーマ、ストレージに関するよくある問題を解決する。

---

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

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

---

リソース

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