better-auth-best-practices

TypeScript のプロジェクトに Better Auth で認証を入れるときです。メール＋パスワード、OAuth、プラグインの設定が対象です。

中心は版の合わせ込み

このスキルの中心は、機能の説明ではなく版の合わせ込みです。冒頭の節がまるごとそれに割かれています。次の順で版を決めます。

1. 利用者の指定利用者が版を指定していればそれを使う
2. ロックファイルなければロックファイルで解決済みの better-auth の版を見る（無ければパッケージの定義を見る）
3. MCP の get_docBetter Auth の MCP があれば get_doc で /llms.txt を呼び、その版に対応するドキュメントの識別子を得る
4. llms.txt の索引MCP が無ければ better-auth.com/llms.txt から版の索引をたどる
5. 最新のドキュメント版が判別できないときか、利用者が最新版や移行を尋ねたときだけ使う

版によって API とプラグイン名が変わる

これが効く理由は明確です。認証ライブラリは版によって API とプラグイン名が変わります。

エージェントが最新のドキュメントを前提に書いたコードを、1 つ前の版のプロジェクトに入れると動きません。そして認証は、動かないことに気づくのが遅れると被害が大きい部分です。

アップグレードでは今の版と移行先を分ける

アップグレードを計画するときは「いま入っている版の案内」と「移行先の版の案内」を分けて示すという指示もあります。混ぜて説明されると判断できなくなる箇所です。

導入は 6 段階で、最後が実測

導入の手順は 6 段階で、最後が実測になっているのが良いところです。

1. インストールnpm install better-auth
2. 環境変数BETTER_AUTH_SECRET と BETTER_AUTH_URL を環境変数に置く
3. auth.tsauth.ts にデータベースと設定を書く
4. ルートハンドラ使っているフレームワーク用のルートハンドラを作る
5. マイグレーションDrizzle / Prisma / 組み込みで手順が違う
6. 確認GET /api/auth/ok を叩いて { status: "ok" } を確認する

Better Auth 以外の認証には使えません

NextAuth（Auth.js）、Clerk、Supabase Auth、Firebase Authentication は対象外です。ライブラリ名が違えば設定の形も違います。

TypeScript 以外の言語では使えません

対象は TypeScript のプロジェクトだけです。

認証設計そのものを相談したいときには向きません

「そもそもパスワード認証を持つべきか」「多要素認証をどうするか」といった判断は扱っていません。すでに Better Auth を選んだあとの設定手順です。

セキュリティ監査の代わりにはなりません

設定を正しく書く手助けであって、書いた結果が安全かを点検する道具ではありません。

Firestore のルールのような「書いたものを攻撃側から読み直す」用途は firebase-security-rules-auditor が近いです。

解析で見つかった記述

SKILL.md の解析では、パッケージの導入とシェルコマンドの実行の記述が見つかっています（npx auth@latest migrate など）。外部通信とファイル操作の記述は検出されていません。

同梱ファイルはありません。渡すものが少ないスキルです。

実際には認証の設定ファイルを書く

ただし、auth.ts の作成とマイグレーションの実行が手順に入っています。書き込みとして拾っていないのは、それが地の文で書かれているためです。

解析結果は「SKILL.md にそう書かれている」ことの列挙であって、実際の挙動の保証ではありません。

秘密鍵は環境変数に置く

秘密鍵の扱いについて、本文に具体的な指示があります。

• BETTER_AUTH_SECRET は 32 文字以上。openssl rand -base64 32 で生成する
• 環境変数が設定されていない場合にだけ、設定ファイル側に baseURL / secret を書く

本文が名指しする落とし穴

本文の「Common Gotchas」は 8 項目です。設定を書いたあとに効いてくる主なものを挙げます。

• 設定に書くのは ORM のモデル名で、データベースのテーブル名ではない（Prisma の User → users なら "user"）
• プラグインを足したら CLI を流し直す（スキーマが変わる）
• secondaryStorage を設定すると、セッションは既定でそちらに入り、データベースには入らない
• データベースを持たない構成では、セッションはクッキーだけ。キャッシュが切れるとログアウトになる
• session.cookieCache.version を変えると、全員のセッションが無効になる

advanced の disableCSRFCheck と disableOriginCheck には、本文が「⚠️ Security risk」と付けています。メールアドレスの変更（user.changeEmail.enabled）と退会（user.deleteUser.enabled）は既定で無効です。

MCP が無くても、外部のドキュメントサイトに接続する

このスキルは MCP との連携を前提にした書き方を含みます。Better Auth の MCP があればドキュメントの解決に使う、という指示です。

MCP を入れていなくても llms.txt をたどる経路があるので動きますが、外部のドキュメントサイトに接続します。閉じたネットワークでは版の解決ができず、最新版の前提で書かれる可能性があります。

当サイトでの総合順位は下のほう

インストール数は約 12.5 万件（2026-10-21 の上流集計）、star は 212。順位が低いのは普及度と信頼性の軸が効いているためで、あなたが Better Auth を使っているなら順位は関係ありません。

セキュリティ・監査の分類は収録が少なく、そのうちクラウド事業者に依存しないものは限られます。

版が分からないときはどうなりますか

本文の指示では、版が判別できないとき（または利用者が最新版や移行について尋ねたとき）だけ最新のドキュメントを使います。ロックファイルがあるなら必ず読ませてください。依頼文に「ロックファイルから版を確認して」と入れるのが確実です。

マイグレーションはどれを使えばいいですか

すでにプロジェクトで使っている ORM に合わせます。

Drizzle は開発時と本番で手順が分かれています（push と generate＋migrate）。本番に push を使わないでください。本文でも分けて書かれています。

`auth.ts` はどこに置けばいいですか

CLI が探すのは ./、./lib、./utils、./src 配下です。別の場所に置くなら --config で指定します。探索の対象外に置いて「見つからない」で止まるのが、このスキルを使うときに最初に踏みやすい落とし穴です。