better-auth-scaffold

Better Auth スキャフォールド（Next.js + Drizzle）

Drizzle アダプターを使用して Next.js App Router プロジェクトに Better Auth のセットアップを構築するための、パラメーター指定可能なテンプレートです。各テンプレートでは、references/conventions.md に記載されている規約（ファイル構成、プラグインの順序、環境変数の扱い、ランタイムの選択）に従います。

適用するタイミング

以下の場合に、これらのテンプレートを参照してください。

• 認証が必要な新しい Next.js プロジェクトを開始するとき
• 既存の Next.js + Drizzle コードベースに Better Auth を追加するとき
• キャッチオールルート、ミドルウェア、または nextCookies() の順序が不足している、不完全な Better Auth セットアップをリファクタリングするとき
• 既存のプロジェクトに機能ごとのバリエーション（minimal、social、advanced）を追加するとき

セットアップ

必須パラメーター

パラメーター	必須	デフォルト	説明
preset	いいえ	minimal	minimal（メール＋パスワード）| social（Google + GitHub を追加）| advanced（social + twoFactor + magicLink）
db_provider	はい	—	pg | mysql | sqlite（Drizzle プロバイダー）
app_name	はい	—	表示名（preset=advanced の場合、認証アプリで2FAの発行者名として使用されます）

任意のパラメーター

パラメーター	デフォルト	説明
auth_path	lib/auth.ts	サーバー認証モジュールのパス
client_path	lib/auth-client.ts	クライアントモジュールのパス
api_route_path	app/api/auth/[...all]/route.ts	キャッチオールルートハンドラーのパス
protected_paths	["/dashboard"]	ミドルウェアで保護するルート

config.json がすでに存在し、値が設定されている場合は、その値を使用します。それ以外の場合は、ユーザーに確認します。

利用可能なテンプレート

テンプレート	出力ファイル	出力するタイミング
auth.ts.template	lib/auth.ts	常に
auth-client.ts.template	lib/auth-client.ts	常に
route.ts.template	app/api/auth/[...all]/route.ts	常に
middleware.ts.template	middleware.ts	protected_paths が空でない場合
env.template	.env.example	常に
db-schema-better-auth.ts.template	db/schema/auth.ts	常に（スタブ — better-auth generate の出力に置き換えてください）
db-index.ts.template	db/index.ts	プロジェクトに Drizzle クライアントがまだない場合
email.ts.template	lib/email.ts	preset=advanced の場合（ファイルがまだ存在しない場合）
sign-in-page.tsx.template	app/sign-in/page.tsx	プロジェクトにサインインページがない場合（ミドルウェアのリダイレクトループを解消します）
permissions.ts.template	lib/permissions.ts	org/admin プラグイン作業用の任意のスターター

使用方法

1. パラメーターを解決します。 まず config.json を読み込みます。必須パラメーター（db_provider、app_name）が不足している場合は、AskUserQuestion を使ってユーザーに質問します。

2. 各テンプレートをレンダリングします。 各テンプレートファイルについて、次の手順を行います。

   • テンプレートを読み込みます。
   • {{placeholder}} の値（{{app_name}}、{{db_provider}} など）を、解決済みのパラメーター値に置き換えます。
   • 次のルールに従って、PRESET[...] 条件ブロックを適用します。
     1. // PRESET[<tags>] と // /PRESET[<tags>] のマーカー行のペアをすべて探します（JS 以外のファイルでは /* PRESET[...] */ または # PRESET[...] を使用します。構文は同じで、コメント形式が異なります）。
     2. <tags> をカンマ区切りのリストとして解析します（例：social,advanced）。
     3. 選択したプリセット値が <tags> に含まれている場合は、2 つのマーカー行だけを削除し、その間の行は残します。
     4. 選択したプリセット値が <tags> に含まれていない場合は、両方のマーカー行を含むブロック全体を削除します。
     5. マーカーはネストしている場合があります（例：PRESET[minimal,social,advanced] 内の PRESET[advanced]）。内側から順に処理します。
   • middleware.ts.template の Mustache 形式の反復（// {{#protected_paths}} ... // {{/protected_paths}}）では、リスト内の各項目につきマーカー間の行を 1 回ずつ繰り返し、{{path}} を各値に置き換えます。

3. 出力ファイルを書き込みます。 書き込む前に、対象ファイルがすでに存在するか確認します。

   • 存在しない場合 → 書き込みます。
   • 存在し、内容が同一の場合 → 何もしません。
   • 存在し、内容が異なる場合 → 差分を表示し、ユーザーに確認します（上書き／マージ／スキップ）。

4. CLI の手順を実行します。 すべてのファイルを書き込んだ後、次を実行します。

   npx @better-auth/cli@latest generate
   npx drizzle-kit generate
   npx drizzle-kit migrate
   

   これらのコマンドは、プレースホルダーの db/schema/auth.ts を実際のスキーマに置き換え、マイグレーションを適用します。

5. 次の手順を表示します。 ユーザーに次の作業を伝えます。

   • .env.example をコピーして .env.local に必要事項を入力する
   • シークレットを生成する：openssl rand -base64 32
   • 各プロバイダーのコンソールで OAuth リダイレクト URI を登録する（social／advanced プリセットの場合）
   • トランザクションメールを接続するために lib/email.ts を実装する（advanced プリセットの場合）

規約

各テンプレートに含まれる規約の理由については、references/conventions.md を参照してください。主な内容は次のとおりです。

• lib/auth.ts はサーバー専用です（import "server-only"）
• nextCookies() は配列内で必ず最後のプラグインにします
• ミドルウェアでは Cookie の有無だけを確認し、実際の検証はページで行います
• すべてのシークレットはインラインで記述せず、process.env.* を使います
• cookieCache を有効にしたスライディングウィンドウセッション

関連スキル

• better-auth — セットアップ、セッション、セキュリティ、プラグイン、マイグレーションに関する 42 のルールを含む、ライブラリ／API リファレンスです。このテンプレートは、それらのルールを実現する標準的な方法の 1 つです。変更が必要な場合は、根拠を確認するために該当するルールを読んでください。

注意点

gotchas.md を参照してください。現在は空のファイルで、注意点が判明するたびに追記されます。