better-auth

Better Auth のベストプラクティス

フレームワークに依存しない TypeScript の認証・認可ライブラリである Better Auth の実装・移行ガイドです。このスキルには、公式ドキュメントと移行ガイドに基づいた 42 のルールが含まれており、影響度に応じて 8 つのカテゴリに分類されています。

適用するタイミング

次のような場合に、このガイドラインを参照してください。

• Better Auth の新しいインスタンスをセットアップするとき（設定、アダプター、ルートハンドラー、クライアント）
• フレームワーク固有のインテグレーションを接続するとき（Next.js App Router／Pages Router、SvelteKit、Hono、Express、Nuxt、Astro）
• セッション、Cookie、セキュリティを設定するとき（レート制限、信頼されたオリジン、パスワードハッシュ化）
• プラグインを追加するとき：2FA、organization、admin、magicLink、JWT、passkey、multi-session
• 別の認証ライブラリから移行するとき（NextAuth/Auth.js、Clerk、Auth0、Supabase Auth）
• 「session is null」／「redirect_uri_mismatch」／403 CSRF エラーをデバッグするとき
• lib/auth.ts、auth-client.ts、または /api/auth/ のルートハンドラーに関する PR をレビューするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	セットアップと設定	CRITICAL	setup-
2	データベースアダプターとスキーマ	CRITICAL	db-
3	API ルートハンドラー	CRITICAL	route-
4	セッションと Cookie	HIGH	session-
5	認証方式とプロバイダー	HIGH	auth-
6	セキュリティと強化	HIGH	security-
7	プラグインと拡張機能	MEDIUM	plugins-
8	他の認証ライブラリからの移行	MEDIUM	migrate-

クイックリファレンス

1. セットアップと設定（CRITICAL）

• setup-secret — 環境ごとに強力な BETTER_AUTH_SECRET を設定します
• setup-base-url — 環境ごとに明示的な baseURL を設定します
• setup-client-base-url — クライアントの baseURL をサーバーと一致させます
• setup-singleton — サーバー専用モジュールから単一の認証インスタンスをエクスポートします
• setup-trusted-origins — baseURL 以外から呼び出すすべてのアクセス元に対して trustedOrigins を設定します

2. データベースアダプターとスキーマ（CRITICAL）

• db-adapter-selection — ORM に合ったアダプターを選択します
• db-schema-generate — デプロイのたびに auth generate を実行し、その後 ORM のマイグレーションを実行します
• db-additional-fields — additionalFields を使ってユーザースキーマを拡張します
• db-plugin-schema-customization — schema オプションを使ってプラグインのテーブル名を変更します
• db-database-hooks — 横断的なロジックには databaseHooks を使います
• db-connection-pooling — アプリの他の部分と、プールされた DB クライアントを 1 つ共有します

3. API ルートハンドラー（CRITICAL）

• route-mount-catchall — /api/auth/[...all] にキャッチオールハンドラーをマウントします
• route-runtime-selection — auth.api を呼び出すミドルウェアには Node.js ランタイムを使います
• route-no-body-consumers — ボディー解析ミドルウェアより前に認証をマウントします

4. セッションと Cookie（高）

• session-server-vs-client — サーバーでは auth.api.getSession、クライアントでは authClient.useSession を使用します
• session-expiry-tuning — expiresIn と updateAge を併せて設定します
• session-cookie-cache — cookieCache を有効にして、セッションの DB 照会を削減します
• session-cookie-attributes — クロスサイトのフローでは sameSite、secure、partitioned を設定します
• session-cross-subdomain — 複数サブドメインのアプリでは crossSubDomainCookies を有効にします
• session-customsession-fields — customSession を使用して計算フィールドを追加します

5. 認証方式とプロバイダー（高）

• auth-require-email-verification — sendVerificationEmail と併せて requireEmailVerification を有効にします
• auth-oauth-redirect-uri — OAuth の redirectURI をプロバイダーのコンソールと完全に一致させます
• auth-oauth-env-vars — OAuth の認証情報は環境変数から読み込み、コードに直接記述しないでください
• auth-magic-link-setup — magicLink プラグインを有効にする前に sendMagicLink を実装します
• auth-client-sign-in-helpers — callbackURL と併せて authClient.signIn.social を使用します
• auth-infer-additional-fields — 型を同期するため、クライアントに inferAdditionalFields を追加します

6. セキュリティと強化（高）

• security-rate-limit — 本番環境では永続ストレージと併せて rateLimit を有効にします
• security-password-hash-interop — bcrypt／argon2 から移行する際は、ハッシュ関数をオーバーライドします
• security-revoke-on-password-reset — revokeSessionsOnPasswordReset を有効にします
• security-min-password-length — minPasswordLength を 10 以上に設定します
• security-trusted-origins-strict — trustedOrigins にワイルドカードを指定しないでください

7. プラグインと拡張機能（中）

• plugins-next-cookies-last — Next.js では nextCookies() を最後のプラグインとして配置します
• plugins-two-factor-issuer — 2FA の発行者として appName を設定します
• plugins-shared-access-control — ac とロールを一度だけ定義し、サーバーとクライアントで共有します
• plugins-pair-client-server — すべてのサーバープラグインに対応するクライアント側のプラグインを組み合わせます
• plugins-organization-active-context — セッションでアクティブな組織を設定します
• plugins-jwt-when-to-use — 外部サービスの利用者向けにのみ jwt プラグインを使用します
• plugins-admin-impersonation — サポート対応のアクセスには、admin プラグインの impersonate メソッドを使用します

8. 他の認証方式からの移行（中）

• migrate-parallel-cutover — 切り替え期間中、Better Auth を従来の認証方式と並行して実行します
• migrate-oauth-account-mapping — 従来の OAuth ID を account 行に対応付けます
• migrate-force-allow-id — 既存のユーザー ID を保持するために forceAllowId を使用します
• migrate-nextauth-schema-mapping — NextAuth v5 の列をフィールドごとに対応付けます

使用方法

新規に実装する場合は、優先順位に従って読み進めてください。まず setup- ルールをすべて読み、次に db-、その後 route- を読みます。これらの CRITICAL カテゴリが正しく設定されていないと、ほかの機能は動作しません。基盤を整えたら、対象範囲に合ったルールを選んでください。Cookie や有効期限の調整には session-、プロバイダーの設定には auth-、本番環境の強化には security- を参照してください。

別の認証ライブラリから移行する場合は、まず migrate-parallel-cutover（戦略）、次に security-password-hash-interop（ユーザーパスワードの保持）、その後 migrate-oauth-account-mapping と migrate-nextauth-schema-mapping（データ構成）を読んでください。

詳細な説明、誤ったコードと正しいコードの例、Better Auth の公式ドキュメントへのリンクについては、個別のリファレンスファイルを参照してください。

リファレンスファイル

ファイル	説明
references/_sections.md	影響度順に並べたカテゴリの定義
assets/templates/_template.md	新しいルールを追加するためのテンプレート
metadata.json	バージョン、リファレンス、規律に関するメタデータ