OpenSkillIndex← back to search
claude-code

Awesome-omni-skill better-auth-best-practices

Better Auth（TypeScript 認証フレームワーク）の統合ガイド。セットアップ、セッション管理、プラグイン、セキュリティ設定に精通。

install
source · Clone the upstream repo
git clone https://github.com/diegosouzapw/awesome-omni-skill
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/testing-security/better-auth-best-practices-nisshi-dev" ~/.claude/skills/diegosouzapw-awesome-omni-skill-better-auth-best-practices-842a0e && rm -rf "$T"
manifest: skills/testing-security/better-auth-best-practices-nisshi-dev/SKILL.md
source content

Better Auth 統合ガイド

コード例と最新 API は better-auth.com/docs を必ず参照すること。

Better Auth は TypeScript ファーストでフレームワーク非依存の認証フレームワーク。メール/パスワード、OAuth、マジックリンク、パスキーなどをプラグインでサポート。

クイックリファレンス

環境変数

  • BETTER_AUTH_SECRET
    - 暗号化シークレット（最低 32 文字）。生成: 
    openssl rand -base64 32
  • BETTER_AUTH_URL
    - ベース URL（例: 
    https://example.com
    ）

環境変数が設定されていない場合のみ、config で 

baseURL
/
secret
を定義する。

ファイルの配置場所

CLI は 

auth.ts
を以下の順で検索: 
./
, 
./lib
, 
./utils
, または 
./src
配下。カスタムパスは 
--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 はアダプターのモデル名を使用し、DB のテーブル名は使わない。Prisma モデルが 

User
でテーブルが 
users
にマッピングされている場合、
modelName: "user"
（Prisma の参照名）を使い、
"users"
ではない。

セッション管理

ストレージの優先順位:

  1. secondaryStorage
    が定義されている場合 → セッションはそこに保存（DB ではない）
  2. DB にも永続化する場合は 
    session.storeSessionInDatabase: true
    を設定
  3. DB なし + 
    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. モデル名 vs テーブル名 - 設定では ORM のモデル名を使用し、DB のテーブル名は使わない
  2. プラグインのスキーマ - プラグイン追加後に CLI を再実行する
  3. セカンダリストレージ - セッションはデフォルトでそちらに保存され、DB には保存されない
  4. Cookie キャッシュ - カスタムセッションフィールドはキャッシュされず、常に再取得される
  5. ステートレスモード - DB なし = セッションは Cookie のみ、キャッシュ期限でログアウト
  6. メールアドレス変更フロー - まず現在のメールに送信、その後新しいメールに送信

リソース