better-auth

better-auth

ステータス: 本番環境で利用可能 最終更新日: 2026-04-08 パッケージ: [email protected]（ESM のみ） 依存関係: Drizzle ORM または Kysely（D1 の複雑なユースケースで必要。D1 のネイティブサポートは v1.5+ で利用可能）

---

クイックスタート（5 分）

インストール

オプション 1：Drizzle ORM（推奨）

bun add better-auth drizzle-orm drizzle-kit

オプション 2：Kysely

bun add better-auth kysely @noxharmonium/kysely-d1

⚠️ v1.4.0+ の要件

better-auth v1.4.0+ はESM のみです。以下を確認してください。

package.json:

{
  "type": "module"
}

v1.3.x からアップグレードしますか？ references/migration-guide-1.4.0.md を読み込んでください。 v1.4.x からアップグレードしますか？ references/migration-guide-1.5.0.md を読み込んでください。

⚠️ 重要：D1 アダプターの要件

v1.5.0+：D1 がネイティブでサポートされるようになりました。D1 バインディングを直接渡してください。

// ✅ SIMPLEST - D1 native (v1.5.0+)
import { betterAuth } from "better-auth";

const auth = betterAuth({
    database: env.DB, // D1 binding, auto-detected
});

複雑なスキーマには、Drizzle ORM を使用してください。

// ✅ RECOMMENDED for complex schemas - Drizzle
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle } from "drizzle-orm/d1";

const auth = betterAuth({
    database: drizzleAdapter(drizzle(env.DB, { schema }), { provider: "sqlite" }),
});

// ❌ WRONG - This doesn't exist
import { d1Adapter } from 'better-auth/adapters/d1'

最小構成（Cloudflare Workers + Drizzle）

1. D1 データベースを作成する：

wrangler d1 create my-app-db

2. スキーマを定義する（src/db/schema.ts）：

import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const user = sqliteTable("user", {
  id: text().primaryKey(),
  name: text().notNull(),
  email: text().notNull().unique(),
  emailVerified: integer({ mode: "boolean" }).notNull().default(false),
  image: text(),
});

export const session = sqliteTable("session", {
  id: text().primaryKey(),
  userId: text().notNull().references(() => user.id, { onDelete: "cascade" }),
  token: text().notNull(),
  expiresAt: integer({ mode: "timestamp" }).notNull(),
});

// See references/database-schema.ts for complete schema

3. 認証を初期化する（src/auth.ts）：

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle } from "drizzle-orm/d1";
import * as schema from "./db/schema";

export function createAuth(env: { DB: D1Database; BETTER_AUTH_SECRET: string }) {
  const db = drizzle(env.DB, { schema });

  return betterAuth({
    baseURL: env.BETTER_AUTH_URL,
    secret: env.BETTER_AUTH_SECRET,
    database: drizzleAdapter(db, { provider: "sqlite" }),
    emailAndPassword: { enabled: true },
  });
}

4. Worker を作成する（src/index.ts）：

import { Hono } from "hono";
import { createAuth } from "./auth";

const app = new Hono<{ Bindings: Env }>();

app.all("/api/auth/*", async (c) => {
  const auth = createAuth(c.env);
  return auth.handler(c.req.raw);
});

export default app;

5. デプロイする：

bunx drizzle-kit generate
wrangler d1 migrations apply my-app-db --remote
wrangler deploy

---

判断ツリー

コード例と構文については、必ず better-auth.com/docs を参照してください。

Is this a new/empty project?
├─ YES → New project setup
│   1. Identify framework (Next.js, Nuxt, Workers, etc.)
│   2. Choose database (D1, PostgreSQL, MongoDB, MySQL)
│   3. Install better-auth + Drizzle/Kysely
│   4. Create auth.ts + auth-client.ts
│   5. Set up route handler (see Quick Start above)
│   6. Run migrations (Drizzle Kit for D1)
│   7. Add features via plugins (2FA, organizations, etc.)
│
└─ NO → Does project have existing auth?
    ├─ YES → Migration/enhancement
    │   • Audit current auth for gaps
    │   • Plan incremental migration
    │   • See references/framework-comparison.md for migration guides
    │
    └─ NO → Add auth to existing project
        1. Analyze project structure
        2. Install better-auth + adapter
        3. Create auth config (see Quick Start)
        4. Add route handler to existing routes
        5. Run schema migrations
        6. Integrate into existing pages/components

---

重要なルール

必ず行うこと

✅ 最小のバンドルには better-auth/minimal とアダプターパッケージを使用する（v1.5+） ✅ CLI コマンドには npx auth migrate と npx auth generate を使用する（v1.5+） ✅ wrangler secret put を使って BETTER_AUTH_SECRET を設定する ✅ credentials: true を指定して CORS を設定する ✅ OAuth コールバック URL を完全に一致させる（末尾のスラッシュなし） ✅ wrangler dev の前にローカル D1 にマイグレーションを適用する ✅ スキーマでは camelCase のカラム名を使用する

絶対に行わないこと

❌ d1Adapter を使用する（存在しません） ❌ CORS の認証情報設定を忘れる、または OAuth URL を一致させない ❌ CamelCasePlugin を使わずに snake_case のカラムを使用する ❌ ローカルマイグレーションを省略する、またはシークレットをハードコードする ❌ sendVerificationEmail を未実装のままにする

⚠️ v1.5.0 の破壊的変更

API Key プラグインの移動：

- import { apiKey } from "better-auth/plugins";
+ import { apiKey } from "@better-auth/api-key";

スキーマ：userId が referenceId に変更され、新しい configId フィールドが追加されました。

After Hooks：データベースの after-hook は、トランザクション内ではなく、トランザクション後に実行されるようになりました。

非推奨 API の削除：Adapter は DBAdapter に変更され、InferUser／InferSession は削除されました。@better-auth/core/utils はサブパスのエクスポートに分割されました。

<1.5.0 からアップグレードする場合は、references/migration-guide-1.5.0.md を読み込んでください

⚠️ v1.6.0 の破壊的変更

セッションの有効期間：freshAge は updatedAt ではなく createdAt を使用するようになりました。機密性の高い操作では、再認証がより頻繁に必要になる場合があります。

SAML のセキュリティ：InResponseTo の検証がデフォルトで有効になりました。無効にするには saml: { enableInResponseToValidation: false } を設定してください。

OIDC Provider の非推奨化：代わりに @better-auth/oauth-provider を使用してください。

v1.5.0 の新機能（概要）

• 新しい CLI：npx auth init/migrate/generate/upgrade
• D1 ネイティブ対応：D1 バインディングを直接渡せます（アダプターは不要）
• OAuth 2.1 Provider：@better-auth/oauth-provider（MCP 対応）
• Electron：デスクトップアプリ向けの @better-auth/electron
• i18n：エラー翻訳向けの @better-auth/i18n
• 動的な Base URL：複数ドメイン／プレビュー環境へのデプロイをサポート
• シークレットキーのローテーション：破壊的変更のないバージョン管理されたシークレット
• テストユーティリティ：ファクトリー、OTP の取得、ログインヘルパー
• 型付きエラーコード：エラーレスポンスに機械可読な code を含めます

詳しい実装ガイドについては、references/v1.5-features.md を読み込んでください。

v1.6.0 の新機能（概要）

• OpenTelemetry：分散トレーシング（実験的）
• パスキーの事前認証：セッション開始前にパスキーを登録
• ノンブロッキング Scrypt：libuv スレッドプールでパスワードをハッシュ化
• パッケージサイズを 46% 削減：4.2MB → 2.3MB
• 大文字と小文字を区別しないクエリ：アダプターのクエリで mode: "insensitive" を指定

詳しい実装ガイドについては、references/v1.6-features.md を読み込んでください。

---

クイックリファレンス

環境変数

変数	用途	例
BETTER_AUTH_SECRET	暗号化シークレット（32 文字以上）	生成：openssl rand -base64 32
BETTER_AUTH_URL	ベース URL	https://example.com または http://localhost:8787
DATABASE_URL	データベース接続（D1 では任意）	PostgreSQL/MySQL 接続文字列

注：環境変数が設定されていない場合に限り、設定で baseURL／secret を定義してください。

CLI コマンド（v1.5 以降）

コマンド	用途
npx auth init	対話形式でプロジェクトを作成
npx auth migrate	データベースのマイグレーションを実行
npx auth generate	認証スキーマを生成
npx auth generate --adapter drizzle	アダプター固有のスキーマ
npx auth upgrade	最新バージョンにアップグレード
bunx drizzle-kit generate	D1：これを使用して Drizzle マイグレーションを生成
wrangler d1 migrations apply DB_NAME	D1：これを使用してマイグレーションを適用

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

コア設定オプション

オプション	備考
appName	任意の表示名
baseURL	BETTER_AUTH_URL が設定されていない場合に限る
basePath	デフォルトは /api/auth。ルートには / を設定します。
secret	BETTER_AUTH_SECRET が設定されていない場合に限る（32 文字以上）
database	ほとんどの機能で必須です。D1 では drizzleAdapter() または Kysely を使用します
secondaryStorage	セッションとレート制限用の Redis/KV
emailAndPassword	有効にするには { enabled: true } を設定します
socialProviders	{ google: { clientId, clientSecret }, ... }
plugins	プラグインの配列（専用パスからインポート）
trustedOrigins	クロスオリジンリクエスト用の CSRF 許可リスト

一般的なプラグイン

専用パッケージからインポートします（v1.5 以降に分離）：

import { twoFactor } from "better-auth/plugins/two-factor"
import { organization } from "better-auth/plugins/organization"
import { passkey } from "@better-auth/passkey"          // Separate package
import { apiKey } from "@better-auth/api-key"            // Separate package (v1.5+)
import { sso } from "@better-auth/sso"                   // Separate package (v1.5+)
import { i18n } from "@better-auth/i18n"                 // Separate package (v1.5+)
import { oauthProvider } from "@better-auth/oauth-provider" // Separate package (v1.5+)

コアプラグイン（引き続き better-auth/plugins にあります）：twoFactor、organization、admin、anonymous、emailOTP、magicLink、phone-number、multi-session、custom-session。

---

エラーのトップ 5（全 15 件は references/error-catalog.md を参照）

エラー #1：「d1Adapter is not exported」

問題：存在しない d1Adapter を使用しようとしている 解決策：代わりに drizzleAdapter または Kysely を使用します（上記のクイックスタートを参照）

エラー #2：スキーマ生成の失敗

問題：better-auth migrate は D1 で動作しない 解決策：bunx drizzle-kit generate の後に wrangler d1 migrations apply を使用します

エラー #3：キャメルケースとスネークケースの不一致

問題：データベースでは email_verified を使用しているが、better-auth は emailVerified を想定している 解決策：スキーマでキャメルケースを使用するか、Kysely に CamelCasePlugin を追加します

エラー #4：CORS エラー

問題：Access-Control-Allow-Origin エラーが発生し、Cookie が送信されない 解決策：credentials: true と正しいオリジンを指定して CORS を設定します

エラー #5：OAuth リダイレクト URI の不一致

問題：ソーシャルサインインが「redirect_uri_mismatch」で失敗する 解決策：次の URI と完全に一致していることを確認します：https://yourdomain.com/api/auth/callback/google

詳細な解決策を含む全 15 件のエラーについては、references/error-catalog.md を読み込んでください。

---

一般的なユースケース

ユースケース 1：メール／パスワード認証

使用場面：ソーシャルプロバイダーを使わない基本的な認証 簡単な実装パターン：

// Client
await authClient.signIn.email({
  email: "[email protected]",
  password: "password123",
});

// Server - enable in config
emailAndPassword: {
  enabled: true,
  requireEmailVerification: true,
}

読み込み先：references/setup-guide.md → ステップ 5

ユースケース 2：ソーシャル認証（45 以上のプロバイダー）

使用場面：ユーザーがソーシャルアカウントでサインインできるようにする 対応プロバイダー：Google、GitHub、Microsoft、Apple、Discord、TikTok、Twitch、Spotify、LinkedIn、Slack、Reddit、Facebook、Twitter/X、Patreon、Vercel、Kick、その他 30 以上。 簡単な実装パターン：

// Client
await authClient.signIn.social({
  provider: "google",
  callbackURL: "/dashboard",
});

// Server config
socialProviders: {
  google: {
    clientId: env.GOOGLE_CLIENT_ID,
    clientSecret: env.GOOGLE_CLIENT_SECRET,
    scope: ["openid", "email", "profile"],
  },
}

読み込み先：references/setup-guide.md → ステップ 5

ユースケース 3：保護された API ルート

使用場面：ユーザーが認証済みかどうかを確認する必要がある 簡単な実装パターン：

app.get("/api/protected", async (c) => {
  const auth = createAuth(c.env);
  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  return c.json({ data: "protected", user: session.user });
});

読み込み先：references/cloudflare-worker-drizzle.ts

ユースケース 4：組織を使ったマルチテナント

使用場面：チーム／組織向けの SaaS を構築する 読み込み先：references/advanced-features.md → 組織とチーム

ユースケース 5：2 要素認証

タイミング：2FA／TOTP によるセキュリティ強化が必要な場合 読み込み：references/advanced-features.md → 2 要素認証

---

リファレンスを読み込むタイミング

references/setup-guide.md を読み込む場合：

• ユーザーが全 8 ステップのセットアップ手順を必要としている
• ユーザーが Kysely アダプターの代替手段について質問している
• ユーザーがマイグレーションまたはデプロイに関するサポートを必要としている
• ユーザーが wrangler.toml の設定について質問している

references/error-catalog.md を読み込む場合：

• 文書化されている 15 件のエラーのいずれかが発生した
• ユーザーから D1 アダプター、スキーマ、CORS、または OAuth の問題が報告された
• ユーザーがトラブルシューティングまたはデバッグについて質問している
• ユーザーが予防チェックリストを必要としている

references/advanced-features.md を読み込む場合：

• ユーザーが 2FA、パスキー、またはマジックリンクについて質問している
• ユーザーが組織、チーム、または RBAC を必要としている
• ユーザーがレート制限またはセッション管理について質問している
• ユーザーが Clerk または Auth.js からの移行ガイドを求めている
• ユーザーがセキュリティのベストプラクティスまたはパフォーマンス最適化を必要としている

references/v1.5-features.md を読み込む場合：

• ユーザーが新しい CLI、MCP 認証、OAuth 2.1 Provider について質問している
• ユーザーが Electron デスクトップ認証または i18n エラー翻訳を必要としている
• ユーザーが動的な base URL またはシークレットキーのローテーションについて質問している
• ユーザーが D1 のネイティブサポート（アダプター不要）またはアダプターの切り出しを必要としている
• ユーザーがテストユーティリティ、シートベースの課金、または型付きエラーコードについて質問している
• ユーザーが Cloudflare D1 のネイティブサポート設定を必要としている

references/v1.6-features.md を読み込む場合：

• ユーザーが OpenTelemetry または分散トレーシングについて質問している
• ユーザーがパスキーの事前認証登録（セッション開始前）を必要としている
• ユーザーが大文字と小文字を区別しないデータベースクエリについて質問している
• アップグレード後にセッションの有効期間に関する問題が発生した
• ユーザーが SAML InResponseTo の検証について質問している

references/migration-guide-1.5.0.md を読み込む場合：

• ユーザーが better-auth <1.5.0 から 1.5.0+ にアップグレードしている
• ユーザーが API Key のインポートエラーに遭遇している（userId → referenceId）
• ユーザーがトランザクション後に after フックが実行されることについて質問している
• ユーザーが InferUser／InferSession の型エラーに遭遇している
• ユーザーが @better-auth/core/utils のインポートを更新する必要がある

references/plugins/sso.md を読み込む場合：

• ユーザーが OIDC、OAuth2、または SAML 2.0 を使用した本番環境向け SSO を必要としている
• ユーザーが OIDC ディスカバリー、SAML SLO、またはドメイン検証について質問している
• ユーザーが SSO による組織のプロビジョニングを必要としている
• ユーザーが SAML セキュリティ（InResponseTo、リプレイ保護、タイムスタンプ）について質問している
• ユーザーが SSO ディスカバリーエラーに遭遇している

references/plugins/test-utils.md を読み込む場合：

• ユーザーが Better Auth を使った統合テストまたは E2E テストを作成している
• ユーザーがテストファクトリー（createUser、createOrganization）を必要としている
• ユーザーが認証済みテストセッション（login、getAuthHeaders、getCookies）を必要としている
• ユーザーが検証テスト用の OTP 取得を必要としている

references/integrations/electron.md を読み込む場合：

• ユーザーが Better Auth を使った Electron デスクトップアプリを構築している
• ユーザーがデスクトップ向けのシステムブラウザー OAuth フローを必要としている
• ユーザーがディープリンクまたはカスタムプロトコルスキームについて質問している
• ユーザーが IPC ブリッジまたは手動のトークン交換を必要としている

references/cloudflare-worker-drizzle.ts を読み込む場合：

• ユーザーが Worker の完全な実装例を必要としている
• ユーザーが本番環境に対応したコードを求めている
• ユーザーが保護されたルートを含む認証フロー全体を確認したい

references/cloudflare-worker-kysely.ts を読み込む場合：

• ユーザーが Drizzle より Kysely を希望している
• ユーザーが Kysely 固有の実装について質問している

references/database-schema.ts を読み込む場合：

• ユーザーがすべてのテーブルを含む better-auth の完全なスキーマを必要としている
• ユーザーがカスタムテーブルまたはスキーマの拡張について質問している
• ユーザーがデータベース用の TypeScript 型を必要としている

references/react-client-hooks.tsx を読み込む場合：

• ユーザーが React／Next.js のフロントエンドを構築している
• ユーザーがログインフォーム、セッションフック、または保護されたルートを必要としている
• ユーザーがクライアントサイドの実装について質問している 次の場合は references/configuration-guide.md を読み込みます：
• ユーザーが本番環境の設定について尋ねている
• ユーザーが環境変数の設定または wrangler.toml を必要としている
• ユーザーが動的なベース URL、シークレットのローテーション、または D1 native について尋ねている
• ユーザーが CORS の設定、レート制限、または API キーを必要としている
• ユーザーがセッションの設定（deferSessionRefresh、セカンダリストレージでの検証）について尋ねている

次の場合は references/framework-comparison.md を読み込みます：

• ユーザーが「better-auth と Clerk の比較」または「Auth.js との比較」を尋ねている
• ユーザーが認証フレームワークの選択についてサポートを必要としている
• ユーザーが機能の比較、移行に関するアドバイス、またはコスト分析を求めている

次の場合は references/migration-guide-1.4.0.md を読み込みます：

• ユーザーが better-auth <1.4.0 から 1.4.0 以降にアップグレードしている
• ユーザーが forgetPassword エラーまたは ESM の問題に遭遇している
• ユーザーが破壊的変更または移行手順について尋ねている

次の場合は references/v1.4-features.md を読み込みます：

• ユーザーがバックグラウンドタスクまたはメール送信の遅延について尋ねている
• ユーザーが Patreon、Vercel、または Kick の OAuth プロバイダー設定を必要としている
• ユーザーが better-auth の CLI ツールについて尋ねている
• ユーザーが管理者ロールの権限設定を必要としている

次の場合は references/nextjs/README.md を読み込みます：

• ユーザーが PostgreSQL を使った Next.js アプリ（Cloudflare D1 ではない）を構築している
• ユーザーが組織と 2FA の例を必要としている
• ユーザーが Next.js 固有の実装について尋ねている

次の場合は references/nextjs/postgres-example.ts を読み込みます：

• ユーザーが Next.js の API ルートの完全な実装を必要としている
• ユーザーが組織と 2FA の実際の使用例を見たいと考えている
• ユーザーが Drizzle を使った PostgreSQL の設定について尋ねている

フレームワーク固有の設定

次の場合は references/frameworks/nextjs.md を読み込みます：

• ユーザーが Next.js（App Router または Pages Router）を使って構築している
• ユーザーがミドルウェア、サーバーコンポーネント、または API ルートを必要としている

次の場合は references/frameworks/nuxt.md を読み込みます：

• ユーザーが Nuxt 3 を使って構築している
• ユーザーが H3 ハンドラー、コンポーザブル、またはサーバールートを必要としている

次の場合は references/frameworks/remix.md を読み込みます：

• ユーザーが Remix を使って構築している
• ユーザーが loader/action パターンまたはセッション処理を必要としている

次の場合は references/frameworks/sveltekit.md を読み込みます：

• ユーザーが SvelteKit を使って構築している
• ユーザーがフック、load 関数、またはストアを必要としている

次の場合は references/frameworks/api-frameworks.md を読み込みます：

• ユーザーが Express、Fastify、NestJS、または Hono（Cloudflare 以外）を使って構築している
• ユーザーがミドルウェアまたはルートの設定を必要としている

次の場合は references/frameworks/expo-mobile.md を読み込みます：

• ユーザーが React Native または Expo アプリを構築している
• ユーザーが SecureStore、ディープリンク、またはモバイル認証を必要としている

データベースアダプター

次の場合は references/databases/postgresql.md を読み込みます：

• ユーザーが Drizzle または Prisma と PostgreSQL を使っている
• ユーザーが Neon、Supabase、またはコネクションプーリングの設定を必要としている

次の場合は references/databases/mongodb.md を読み込みます：

• ユーザーが MongoDB を使っている
• ユーザーが Atlas の設定またはインデックスを必要としている

次の場合は references/databases/mysql.md を読み込みます：

• ユーザーが MySQL または PlanetScale を使っている
• ユーザーが Vitess との互換性に関するガイダンスを必要としている

プラグインガイド

次の場合は references/plugins/authentication.md を読み込みます：

• ユーザーが 2FA、パスキー（事前認証を含む）、マジックリンク、メール OTP、または匿名ユーザーを必要としている
• ユーザーが強化された認証方式について尋ねている

次の場合は references/plugins/enterprise.md を読み込みます：

• ユーザーが組織、SSO/SAML、SCIM、または管理者ダッシュボードを必要としている
• ユーザーがマルチテナントまたはエンタープライズアプリケーションを構築している

次の場合は references/plugins/api-tokens.md を読み込みます：

• ユーザーが API キー（組織所有、マルチ設定を含む）、ベアラートークン、JWT を必要としている
• ユーザーがサードパーティー向けの API 認証を構築している

次の場合は references/plugins/payments.md を読み込みます：

• ユーザーが Stripe（シートベースの課金を含む）または Polar との連携を必要としている
• ユーザーがサブスクリプションまたは決済機能を構築している

次の場合は references/plugins/sso.md を読み込みます：

• ユーザーが OIDC、OAuth2、または SAML 2.0 による本番環境向け SSO を必要としている
• ユーザーが OIDC ディスカバリー、SAML SLO、ドメイン検証について尋ねている
• ユーザーが SSO による組織のプロビジョニングを必要としている

次の場合は references/plugins/test-utils.md を読み込みます：

• ユーザーが統合テストまたは E2E テストを書いている
• ユーザーがテストファクトリー、OTP の取得、または認証済みセッションを必要としている

統合ガイド

次の場合は references/integrations/electron.md を読み込んでください：

• Better Auth を使用した Electron デスクトップアプリを構築する場合
• システムブラウザー OAuth、ディープリンク、IPC ブリッジが必要な場合

---

設定リファレンス

クイック設定（v1.4.0 以降は ESM のみ）：

export const auth = betterAuth({
  baseURL: env.BETTER_AUTH_URL,
  secret: env.BETTER_AUTH_SECRET,
  database: drizzleAdapter(db, { provider: "sqlite" }),
});

次の場合は references/configuration-guide.md を読み込んでください：

• メール／パスワードとソーシャルプロバイダーを使用した本番環境の設定
• wrangler.toml の設定と環境変数
• セッション設定、CORS の設定、ESM の要件
• レート制限、API キー（v1.4.0 以降）、トラブルシューティング

---

バンドルされたリソースの使用

リファレンス（references/）

• setup-guide.md - 8 ステップの完全なセットアップ（D1 → Drizzle → デプロイ）
• error-catalog.md - 15 種類すべてのエラーと解決策、予防チェックリスト
• advanced-features.md - 2FA、組織、レート制限、パスキー、マジックリンク、マイグレーション
• configuration-guide.md - 本番環境の設定、動的ベース URL、シークレットローテーション、D1 ネイティブ
• framework-comparison.md - better-auth と Clerk、Auth.js の比較、移行パス、TCO
• migration-guide-1.4.0.md - v1.3.x から v1.4.0 以降へのアップグレード（ESM、API の変更）
• migration-guide-1.5.0.md - v1.4.x から v1.5.0 以降へのアップグレード（API キー、アダプターのインポート、フック）
• v1.4-features.md - バックグラウンドタスク、新しい OAuth プロバイダー、SAML/SSO、CLI
• v1.5-features.md - 新しい CLI、OAuth 2.1 Provider、Electron、i18n、D1 ネイティブ、シークレットローテーション
• v1.6-features.md - OpenTelemetry、パスキーの事前認証、ノンブロッキング scrypt
• cloudflare-worker-drizzle.ts - Drizzle 認証を備えた完全な Worker
• cloudflare-worker-kysely.ts - Kysely 認証を備えた完全な Worker
• database-schema.ts - 完全な better-auth Drizzle スキーマ
• react-client-hooks.tsx - 認証フックを備えた React コンポーネント

フレームワークリファレンス（references/frameworks/）

• nextjs.md - Next.js App/Pages Router の統合
• nuxt.md - H3 とコンポーザブルを使用した Nuxt 3
• remix.md - Remix のローダー、アクション、セッション
• sveltekit.md - SvelteKit のフックとストア
• api-frameworks.md - Express、Fastify、NestJS、Hono
• expo-mobile.md - React Native と Expo

データベースリファレンス（references/databases/）

• postgresql.md - Drizzle/Prisma、Neon/Supabase を使用した PostgreSQL
• mongodb.md - MongoDB アダプターと Atlas
• mysql.md - MySQL と PlanetScale

プラグインリファレンス（references/plugins/）

• authentication.md - 2FA、パスキー（事前認証を含む）、マジックリンク、メール OTP、匿名認証
• enterprise.md - 組織、SSO、SCIM、管理
• api-tokens.md - API キー（組織所有、複数設定を含む）、ベアラートークン、JWT
• payments.md - Stripe、Polar の統合
• sso.md - 本番環境の SSO：OIDC ディスカバリー、SAML SLO、ドメイン検証、セキュリティ
• test-utils.md - テストヘルパー：ファクトリー、OTP の取得、ログイン、Vitest/Playwright

統合リファレンス（references/integrations/）

• electron.md - Electron デスクトップ認証：システムブラウザー OAuth、IPC ブリッジ、ディープリンク

Next.js の例（references/nextjs/）

• README.md - Next.js + PostgreSQL のセットアップガイド（D1 ではありません）
• postgres-example.ts - 組織、2FA、メール検証を備えた完全な API ルート

クライアントの統合

認証クライアントを作成（src/lib/auth-client.ts）：

import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: import.meta.env.VITE_API_URL || "http://localhost:8787",
});

React で使用：

import { authClient } from "@/lib/auth-client";

export function UserProfile() {
  const { data: session, isPending } = authClient.useSession();

  if (isPending) return <div>Loading...</div>;
  if (!session) return <div>Not authenticated</div>;

  return (
    <div>
      <p>Welcome, {session.user.email}</p>
      <button onClick={() => authClient.signOut()}>Sign Out</button>
    </div>
  );
}

---

依存関係

必須：

• better-auth@^1.6.0 - コア認証フレームワーク（ESM 専用）

アダプターを1つ選択（v1.5+ では D1 ネイティブを使う場合は任意）：

• drizzle-orm@^0.45.2 + drizzle-kit@^0.31.10（複雑なスキーマにおすすめ）
• kysely@^0.28.8 + @noxharmonium/kysely-d1@^0.4.0（代替）
• @better-auth/drizzle-adapter + better-auth/minimal（最小のバンドル、v1.5+）

任意：

• @cloudflare/workers-types - Workers 用の TypeScript 型
• hono@^4.12.12 - ルーティング用の Web フレームワーク
• @better-auth/passkey - パスキー／WebAuthn プラグイン
• @better-auth/api-key - 組織サポート付き API キー認証
• @better-auth/sso - 本番環境向け SSO/SAML/OIDC プラグイン
• @better-auth/electron - Electron デスクトップ認証
• @better-auth/i18n - エラーメッセージの翻訳
• @better-auth/oauth-provider - OAuth 2.1 認可サーバー

---

Cloudflare D1 以外について

このスキルでは、Cloudflare Workers + D1 に焦点を当てています。better-auth は次もサポートしています。

フレームワーク（全18種）：Next.js、Nuxt、Remix、SvelteKit、Astro、Express、NestJS、Fastify、Elysia、Expo など。

データベース（9つのアダプター）：PostgreSQL、MongoDB、MySQL、Prisma、MS SQL など。

追加プラグイン：匿名認証、メール OTP、JWT、マルチセッション、OAuth 2.1 プロバイダー、テストユーティリティ、SCIM、決済連携（Stripe、Polar）、デバイス認可。

Cloudflare 以外の構成の場合は、適切なフレームワークまたはデータベースのリファレンスファイルを読み込むか、公式ドキュメントを参照してください：https://better-auth.com/docs

---

公式ドキュメント

• better-auth ドキュメント: https://better-auth.com
• GitHub: https://github.com/better-auth/better-auth (22.4k ⭐)
• サンプル: https://github.com/better-auth/better-auth/tree/main/examples
• Drizzle ドキュメント: https://orm.drizzle.team/docs/get-started-sqlite
• Kysely ドキュメント: https://kysely.dev/
• Discord: https://discord.gg/better-auth

---

フレームワークの比較

次の内容を確認するには references/framework-comparison.md を読み込んでください：

• better-auth、Clerk、Auth.js の機能を網羅的に比較
• v1.4.0+ の新機能（データベース結合、ステートレスセッション、API キー）
• 移行方法、コスト分析、パフォーマンスベンチマーク
• ユースケース別の推奨事項と5年間の TCO

---

本番環境のサンプル

動作確認済みのリポジトリ（すべて Drizzle または Kysely を使用）：

1. zwily/example-react-router-cloudflare-d1-drizzle-better-auth - Drizzle
2. matthewlynch/better-auth-react-router-cloudflare-d1 - Kysely
3. foxlau/react-router-v7-better-auth - Drizzle
4. zpg6/better-auth-cloudflare - Drizzle（CLI を含む）

注：各リポジトリで better-auth のバージョンを確認してください。v1.3.x のリポジトリでは v1.4.0+ への移行が必要です（references/migration-guide-1.4.0.md を参照）。直接 d1Adapter を使用しているものはなく、すべて Drizzle/Kysely が必要です。

---

セキュアなインストール

認証パッケージをインストールする際は、サプライチェーンセキュリティのベストプラクティスに従ってください。認証ライブラリはサプライチェーン攻撃の格好の標的です。

• インストール後のスクリプトをブロック — npm config set ignore-scripts true（または Bun：デフォルトで無効）
• クールダウン期間 — 新しいパッケージバージョンがコミュニティによって検証されるまで7日間待機
• インストール前に監査 — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認

Socket CLI 連携、クールダウン設定、ロックファイルの検証、CI による強制適用など、セキュリティ設定の全容を確認するには、dependency-upgrade スキルを読み込んでください。

セットアップ完了チェックリスト

• ESM のサポートを確認しました（package.json の "type": "module"）— v1.4.0+ が必要です
• [email protected]+（D1 ネイティブ）または Drizzle/Kysely をインストールしました
• wrangler で D1 データベースを作成しました
• データベーススキーマを定義しました（またはスキーマを使わず D1 ネイティブを使用しています）
• マイグレーションを生成し、D1 に適用しました
• BETTER_AUTH_SECRET 環境変数を設定しました
• 認証設定で baseURL を構成しました（またはプレビュー用の動的なベース URL を設定しました）
• 認証方式を有効にしました（emailAndPassword、socialProviders）
• credentials: true を指定して CORS を構成しました
• プロバイダー設定で OAuth コールバック URL を設定しました
• 認証ルート（/api/auth/*）をテストしました
• サインイン、サインアップ、セッション検証をテストしました
• forgetPassword ではなく requestPasswordReset を使用しています（v1.4.0+ API）
• @better-auth/cli ではなく npx auth CLI を使用しています（v1.5.0+）
• API キーには better-auth/plugins ではなく @better-auth/api-key を使用しています（v1.5.0+）
• Cloudflare Workers にデプロイしました

---

ご質問や問題がある場合

1. references/error-catalog.md で 15 個すべてのエラーと解決策を確認してください
2. references/setup-guide.md で 8 ステップの完全なセットアップガイドを確認してください
3. references/advanced-features.md で 2FA、組織などの機能を確認してください
4. 公式ドキュメントを確認してください：https://better-auth.com
5. 存在しない d1Adapter ではなく、Drizzle または Kysely を使用していることを確認してください