better-auth-best-practices

Better Auth 統合ガイド

ドキュメントのバージョン

プロジェクトにインストールされている Better Auth のバージョンに合ったドキュメントを使用してください。API やプラグイン名は、メンテナンスされているリリース系列によって異なる場合があります。

1. ユーザーが明示したバージョンがあれば、優先して使用します。
2. それ以外の場合は、ロックファイルで解決済みの better-auth のバージョンを確認し、ロックファイルがない場合はパッケージマニフェストを確認します。
3. Better Auth MCP を利用できる場合は、/llms.txt を指定して get_doc を呼び出し、そのパッケージバージョンに対応するドキュメント識別子を特定します。すべての search_docs 呼び出しにその識別子を渡し、get_doc には結果のパスを変更せずに渡します。
4. MCP を利用できない場合は、better-auth.com/llms.txt から開始し、該当するバージョンのインデックスを参照します。
5. プロジェクトのバージョンを特定できない場合、またはユーザーが最新リリースやアップグレードについて明示的に尋ねた場合にのみ、最新のドキュメントを使用します。

アップグレードを計画する際は、現在インストールされているバージョン向けのガイダンスと、移行先バージョン向けのガイダンスを分けてください。

---

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

1. インストールします：npm install better-auth
2. 環境変数を設定します：BETTER_AUTH_SECRET と BETTER_AUTH_URL
3. データベースと設定を含む auth.ts を作成します
4. 使用するフレームワーク用のルートハンドラーを作成します
5. マイグレーションを実行します：
   • 組み込みアダプター： npx auth@latest migrate
   • Drizzle： npx auth@latest generate --output src/db/auth-schema.ts の後、npx drizzle-kit push（開発環境）または npx drizzle-kit generate && npx drizzle-kit migrate（本番環境）を実行します
   • Prisma： npx auth@latest generate --output prisma/schema.prisma の後、npx prisma migrate dev を実行します
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 auth@latest migrate - スキーマを適用します（組み込みアダプター）
• npx auth@latest generate - Prisma／Drizzle 用のスキーマを生成します
• npx auth@latest 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 のインスタンスを渡します。Postgres では、postgres（postgres.js）と @neondatabase/serverless もサポートされています。

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

Drizzle のプロバイダー値： "pg"（PostgreSQL）、"mysql"（MySQL）、"sqlite"（SQLite）。使用するドライバーと一致させる必要があります。

重要： Better Auth が使用するのはアダプターのモデル名であり、基になるテーブル名ではありません。Prisma のモデルが User で、テーブル名が users に対応している場合は、"users" ではなく modelName: "user"（Prisma の参照名）を使用します。

---

セッション管理

保存先の優先順位：

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. メールアドレス変更のフロー - まず現在のメールアドレスに送信し、その後、新しいメールアドレスに送信します
7. Drizzle：db が初期化されていない - drizzleAdapter(db, ...) には drizzle() から取得した db インスタンスが必要です。セットアップ例（node-postgres、postgres.js、Neon）については create-auth スキルを参照してください。
8. Drizzle：drizzle.config.ts がない - drizzle-kit コマンドには、生成されたスキーマファイルと DB 認証情報を指定する drizzle.config.ts が必要です。

---

Resources

• Docs
• Options Reference
• LLMs.txt
• GitHub
• Init Options Source