better-auth

Better Auth スキル

Better Auth は、TypeScript 向けの包括的でフレームワークに依存しない認証・認可フレームワークです。メール／パスワード認証、ソーシャル OAuth、高度な機能を実現する強力なプラグインエコシステムを標準で備えています。

使用する場面

• TypeScript／JavaScript アプリケーションに認証を実装する場合
• メール／パスワード認証やソーシャル OAuth 認証を追加する場合
• 2FA、パスキー、マジックリンク、高度な認証機能を設定する場合
• 組織サポートを備えたマルチテナントアプリを構築する場合
• セッションとユーザーのライフサイクルを管理する場合
• あらゆるフレームワーク（Next.js、Nuxt、SvelteKit、Remix、Astro、Hono、Express など）で作業する場合

クイックスタート

インストール

npm install better-auth
# or pnpm/yarn/bun add better-auth

環境設定

.env を作成します：

BETTER_AUTH_SECRET=<generated-secret-32-chars-min>
BETTER_AUTH_URL=http://localhost:3000

基本的なサーバー設定

auth.ts を作成します（ルート、lib/、utils/、または src/app/server/ 配下）：

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: {
    // See references/database-integration.md
  },
  emailAndPassword: {
    enabled: true,
    autoSignIn: true
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }
  }
});

データベーススキーマ

npx @better-auth/cli generate  # Generate schema/migrations
npx @better-auth/cli migrate   # Apply migrations (Kysely only)

API ハンドラーのマウント

Next.js App Router：

// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);

その他のフレームワーク： references/email-password-auth.md#framework-setup を参照してください

クライアント設定

auth-client.ts を作成します：

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

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"
});

基本的な使い方

// Sign up
await authClient.signUp.email({
  email: "[email protected]",
  password: "secure123",
  name: "John Doe"
});

// Sign in
await authClient.signIn.email({
  email: "[email protected]",
  password: "secure123"
});

// OAuth
await authClient.signIn.social({ provider: "github" });

// Session
const { data: session } = authClient.useSession(); // React/Vue/Svelte
const { data: session } = await authClient.getSession(); // Vanilla JS

機能選択マトリックス

機能	プラグインが必要	用途	リファレンス
メール／パスワード	いいえ（標準機能）	基本的な認証	email-password-auth.md
OAuth（GitHub、Google など）	いいえ（標準機能）	ソーシャルログイン	oauth-providers.md
メール認証	いいえ（標準機能）	メールアドレスの確認	email-password-auth.md
パスワードリセット	いいえ（標準機能）	パスワードを忘れた場合のフロー	email-password-auth.md
二要素認証（2FA/TOTP）	はい（twoFactor）	セキュリティの強化	advanced-features.md
パスキー／WebAuthn	はい（passkey）	パスワードレス認証	advanced-features.md
マジックリンク	はい（magicLink）	メールを使ったログイン	advanced-features.md
ユーザー名認証	はい（username）	ユーザー名でのログイン	email-password-auth.md
組織／マルチテナント	はい（organization）	チーム／組織の機能	advanced-features.md
レート制限	いいえ（標準機能）	不正利用の防止	advanced-features.md
セッション管理	いいえ（標準機能）	ユーザーセッション	advanced-features.md

認証方式の選択ガイド

メール／パスワードを選ぶ場合：

• 従来型の認証を備えた標準的なウェブアプリを構築する
• ユーザーの認証情報を完全に制御する必要がある
• メールベースのアカウントを好むユーザーを対象にする

OAuth を選ぶ場合：

• 手間を最小限に抑えてすばやくサインアップできるようにしたい
• ユーザーがすでにソーシャルアカウントを持っている
• ソーシャルプロフィールのデータにアクセスする必要がある

パスキーを選ぶ場合：

• パスワードレスの利用体験を実現したい
• 最新のブラウザー／デバイスを対象にする
• セキュリティを最優先する

マジックリンクを選ぶ場合：

• WebAuthn の複雑さを避けながらパスワードレス認証を実現したい
• メールを優先するユーザーを対象にする
• 一時的なアクセスリンクが必要である

複数の方式を組み合わせる場合：

• ユーザーごとの好みに応じて柔軟に対応したい
• さまざまな認証要件を持つエンタープライズアプリを構築する
• 段階的な拡張が必要である（シンプルに始め、選択肢を追加する）

コアアーキテクチャ

Better Auth はクライアント・サーバーアーキテクチャを採用しています：

1. サーバー（better-auth）：認証ロジック、データベース操作、API ルートを処理します
2. クライアント（better-auth/client）：フロントエンド向けのフック／メソッドを提供します
3. プラグイン：サーバーとクライアントの両方の機能を拡張します

実装チェックリスト

• better-auth パッケージをインストールする
• 環境変数（SECRET、URL）を設定する
• データベース設定を含む認証サーバーインスタンスを作成する
• スキーマのマイグレーションを実行する（npx @better-auth/cli generate）
• フレームワークに API ハンドラーをマウントする
• クライアントインスタンスを作成する
• サインアップ／サインイン UI を実装する
• コンポーネントにセッション管理を追加する
• 保護されたルート／ミドルウェアを設定する
• 必要に応じてプラグインを追加する（追加後にスキーマを再生成する）
• 認証フロー全体をテストする
• メール送信（確認／リセット）を設定する
• 本番環境向けにレート制限を有効にする
• エラー処理を設定する

リファレンスドキュメント

コア認証

• メール／パスワード認証 - メール／パスワードの設定、確認、パスワードのリセット、ユーザー名認証
• OAuth プロバイダー - ソーシャルログインの設定、プロバイダーの構成、トークン管理
• データベース連携 - データベースアダプター、スキーマの設定、マイグレーション

高度な機能

• 高度な機能 - 2FA／MFA、パスキー、マジックリンク、組織、レート制限、セッション管理

スクリプト

• scripts/better_auth_init.py - 対話形式のセットアップで Better Auth の構成を初期化します

リソース

• ドキュメント: https://www.better-auth.com/docs
• GitHub: https://github.com/better-auth/better-auth
• プラグイン: https://www.better-auth.com/docs/plugins
• サンプル: https://www.better-auth.com/docs/examples