better-auth

Better Auth

フレームワークに依存しない TypeScript 認証ライブラリです。プラグインベースのアーキテクチャ、40 以上の OAuth プロバイダー、18 以上のフレームワーク連携に対応しています。

クイックスタート

インストール

npm install better-auth

必要に応じてスコープ付きパッケージを使用します。

パッケージ	用途
@better-auth/passkey	WebAuthn／Passkey 認証
@better-auth/sso	SAML／OIDC エンタープライズ SSO
@better-auth/stripe	Stripe 決済
@better-auth/expo	React Native／Expo

環境変数

BETTER_AUTH_SECRET=<32+ chars, generate: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<connection string>

サーバー設定（lib/auth.ts）

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: process.env.DATABASE_URL,  // or adapter instance
  emailAndPassword: { enabled: true },
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
  plugins: [], // add plugins here
});

export type Session = typeof auth.$Infer.Session;

クライアント設定（lib/auth-client.ts）

import { createAuthClient } from "better-auth/react"; // or /vue, /svelte, /solid, /client

export const authClient = createAuthClient({
  plugins: [], // add client plugins here
});

ルートハンドラー

フレームワーク	ファイル	ハンドラー
Next.js App Router	app/api/auth/[...all]/route.ts	toNextJsHandler(auth)`` → { GET, POST }` をエクスポート
Next.js Pages	pages/api/auth/[...all].ts	toNextJsHandler(auth) → デフォルトエクスポート
Express	任意	app.all("/api/auth/*splat", toNodeHandler(auth))
Hono	ルート	app.on(["POST","GET"], "/api/auth/**", (c) => auth.handler(c.req.raw))
SvelteKit	hooks.server.ts	svelteKitHandler({ auth, event })
Astro	pages/api/auth/[...all].ts	toAstroHandler(auth)
Elysia	プラグイン	new Elysia().mount(auth.handler)

すべてのフレームワークについては、references/framework-integrations.md を参照してください。

CLI コマンド

npx @better-auth/cli@latest migrate          # Apply schema (built-in adapter)
npx @better-auth/cli@latest generate          # Generate for Prisma/Drizzle
npx @better-auth/cli@latest generate --output prisma/schema.prisma
npx @better-auth/cli@latest generate --output src/db/auth-schema.ts

プラグインを追加または変更した後は、再実行してください。

コアコンセプト

• サーバーインスタンス（auth）：すべての認証ロジック、DB、セッションを処理します
• クライアントインスタンス（authClient）：フレームワーク固有のフック（useSession、signIn、signUp、signOut）
• プラグイン：サーバーとクライアントの両方を拡張し、エンドポイント、DB テーブル、フックを追加します
• 型推論：auth.$Infer.Session、auth.$Infer.Session.user により、完全な型安全性を実現します
• クライアントとサーバーが別々のプロジェクトの場合：createAuthClient<typeof auth>()

認証方式

方式	パッケージ	設定／プラグイン	リファレンス
メール／パスワード	組み込み	emailAndPassword: { enabled: true }	authentication.md
ソーシャル OAuth	組み込み	socialProviders: { google: {...} }	authentication.md
マジックリンク	組み込み	magicLink() プラグイン	authentication.md
パスキー	@better-auth/passkey	passkey() プラグイン	authentication.md
ユーザー名	組み込み	username() プラグイン	authentication.md
メール OTP	組み込み	emailOtp() プラグイン	authentication.md
電話番号	組み込み	phoneNumber() プラグイン	authentication.md
匿名	組み込み	anonymous() プラグイン	authentication.md

プラグインのクイックリファレンス

ツリーシェイキングのため、専用のパスからインポートしてください。import { twoFactor } from "better-auth/plugins/two-factor" を使用し、from "better-auth/plugins" は使用しないでください。

プラグイン	サーバーのインポート	クライアントのインポート	用途
twoFactor	better-auth/plugins/two-factor	twoFactorClient	TOTP、OTP、バックアップコード
organization	better-auth/plugins/organization	organizationClient	マルチテナント組織、チーム、RBAC
admin	better-auth/plugins/admin	adminClient	ユーザー管理、なりすまし
passkey	@better-auth/passkey	passkeyClient	WebAuthn/FIDO2
magicLink	better-auth/plugins/magic-link	magicLinkClient	パスワード不要のメールリンク
emailOtp	better-auth/plugins/email-otp	emailOtpClient	メールのワンタイムパスワード
username	better-auth/plugins/username	usernameClient	ユーザー名ベースの認証
phoneNumber	better-auth/plugins/phone-number	phoneNumberClient	電話番号ベースの認証
anonymous	better-auth/plugins/anonymous	anonymousClient	ゲストセッション
apiKey	better-auth/plugins/api-key	apiKeyClient	API キー管理
bearer	better-auth/plugins/bearer	—	ベアラートークン認証
jwt	better-auth/plugins/jwt	jwtClient	JWT トークン
multiSession	better-auth/plugins/multi-session	multiSessionClient	複数のアクティブなセッション
oauthProvider	better-auth/plugins/oauth-provider	—	OAuth プロバイダーになる
oidcProvider	better-auth/plugins/oidc-provider	—	OIDC プロバイダーになる
sso	@better-auth/sso	ssoClient	SAML/OIDC エンタープライズ SSO
openAPI	better-auth/plugins/open-api	—	API ドキュメント
customSession	better-auth/plugins/custom-session	—	セッションデータを拡張
genericOAuth	better-auth/plugins/generic-oauth	genericOAuthClient	カスタム OAuth プロバイダー
oneTap	better-auth/plugins/one-tap	oneTapClient	Google One Tap

パターン：auth({ plugins: [...] }) にサーバープラグインを追加し、createAuthClient({ plugins: [...] }) にクライアントプラグインを追加してから、CLI マイグレーションを再実行します。

詳細な使用方法とカスタムプラグインの作成については、references/plugins.md を参照してください。

データベースのセットアップ

アダプター	セットアップ
SQLite	better-sqlite3 または bun:sqlite のインスタンスを渡します
PostgreSQL	pg.Pool のインスタンスを渡します
MySQL	mysql2 のプールを渡します
Prisma	better-auth/adapters/prisma の prismaAdapter(prisma, { provider: "postgresql" })
Drizzle	better-auth/adapters/drizzle の drizzleAdapter(db, { provider: "pg" })
MongoDB	better-auth/adapters/mongodb の mongodbAdapter(db)
接続文字列	database: process.env.DATABASE_URL（組み込みの Kysely を使用）

重要： 設定では DB テーブル名ではなく、ORM のモデル名を使用します。Prisma モデル User がテーブル users にマッピングされる場合は、modelName: "user" を使用します。

コアスキーマのテーブル：user、session、account、verification。プラグインは独自のテーブルを追加します。

データベースのセットアップの詳細については、references/setup.md を参照してください。

セッション管理

主なオプション：

session: {
  expiresIn: 60 * 60 * 24 * 7,  // 7 days (default)
  updateAge: 60 * 60 * 24,       // refresh every 24h (default)
  freshAge: 60 * 60 * 24,        // require re-auth after 24h for sensitive ops
  cookieCache: {
    enabled: true,
    maxAge: 300,                  // 5 min
    strategy: "compact",          // "compact" | "jwt" | "jwe"
  },
}

• secondaryStorage（Redis/KV）：セッションはデフォルトで DB ではなく、ここに保存されます
• ステートレスモード：DB を使用せず、cookieCache を使用する場合、セッションは Cookie のみに保存されます
• customSession プラグイン：カスタムフィールドでセッションを拡張します

セッション管理の詳細については、references/sessions.md を参照してください。

セキュリティチェックリスト

すること	しないこと
エントロピーの高い32文字以上のシークレットを使用する	シークレットをバージョン管理にコミットする
本番環境では baseURL に HTTPS を設定する	CSRF チェック（disableCSRFCheck）を無効にする
すべてのフロントエンドに trustedOrigins を設定する	オリジンチェックを無効にする
レート制限を有効にする（本番環境ではデフォルトで有効）	サーバーレス環境でレート制限ストレージに "memory" を使用する
サーバーレス環境では backgroundTasks.handler を設定する	メール認証の設定を省略する
機密性の高いセッションデータには "jwe" Cookie キャッシュを使用する	API 呼び出しに OAuth トークンを使用する場合に、暗号化せずに保存する
revokeSessionsOnPasswordReset: true を設定する	具体的なエラーメッセージ（「ユーザーが見つかりません」など）を返す

セキュリティ強化の完全なガイドについては、references/security.md を参照してください。

よくある注意点

1. モデル名とテーブル名 — 設定では DB テーブル名ではなく、ORM モデル名を使用します
2. プラグインのスキーマ — プラグインを追加または変更した後は、CLI を再実行してください
3. セカンダリストレージ — セッションはデフォルトで DB ではなく、そちらに保存されます。両方に永続化するには session.storeSessionInDatabase: true を設定してください
4. Cookie キャッシュ — カスタムセッションフィールドはキャッシュされず、常に DB から再取得されます
5. コールバック URL — 常にオリジンを含む絶対 URL を使用してください（相対パスではなく）
6. Express v5 — キャッチオールルートには "/api/auth/*" ではなく "/api/auth/*splat" を使用してください
7. Next.js RSC — サーバーコンポーネントからセッションにアクセスするには、認証設定に nextCookies() プラグインを追加してください

トラブルシューティング

問題	解決方法
"Secret not set"	BETTER_AUTH_SECRET 環境変数を追加する
"Invalid Origin"	trustedOrigins にドメインを追加する
Cookie が設定されない	baseURL がドメインと一致することを確認し、本番環境ではセキュア Cookie を有効にする
OAuth コールバックエラー	プロバイダーダッシュボードのリダイレクト URI が完全に一致することを確認する
プラグイン追加後に型エラーが発生する	CLI の generate/migrate を再実行する
RSC でセッションが null になる	nextCookies() プラグインを追加する
2FA のリダイレクトが機能しない	クライアントに onTwoFactorRedirect を指定した twoFactorClient を追加する

リファレンス一覧

ファイル	参照するタイミング
setup.md	新しいプロジェクトのセットアップ、DB の設定、ルートハンドラーの設定
authentication.md	認証方式（メール、ソーシャル、パスキー、マジックリンクなど）の実装
sessions.md	セッションの有効期限、キャッシュ、ステートレスモード、セカンダリストレージの設定
security.md	本番環境向けのセキュリティ強化 — レート制限、CSRF、Cookie、OAuth のセキュリティ
plugins.md	プラグインの使用や作成、プラグインカタログ
framework-integrations.md	フレームワーク固有のセットアップ（Next.js、Nuxt、SvelteKit、Hono、Express など）
two-factor.md	2FA（TOTP、OTP、バックアップコード、信頼済みデバイス）の実装
organizations.md	マルチテナント組織、チーム、招待、RBAC
admin.md	ユーザー管理、ロール、利用停止、なりすまし
hooks-and-middleware.md	before/after フック、DB フック、ミドルウェアによるカスタムロジック