mcpField
B
better-auth-ui-react

better-auth-ui-react

github.com/better-auth-ui開発1.7k45 回インストール3 日前に更新
リポジトリ

better-auth-ui-react について

Better Auth UI の共有データレイヤー、プロバイダー、認証フックを React に組み込む開発者向けガイドです。SSR、ルーティング、クエリーキャッシュ、プラグイン設定の注意点も扱います。

主な機能

  1. 01認証クライアントとUIプロバイダーを設定
  2. 02セッション照会と認証更新フックを利用
  3. 03ブラウザーおよびサーバーローダーを設定
  4. 04リクエスト単位のクエリークライアントでSSRに対応
  5. 05プラグインと組織ルートを設定

活用シーン

  1. 01ReactアプリにBetter Auth UIを導入
  2. 02認証ページのナビゲーションとリダイレクトを設定
  3. 03SSRでセッションを読み込みハイドレーション
  4. 04ルートに応じて組織を選びプラグイン画面を有効化

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/better-auth-ui/better-auth-ui --skill better-auth-ui-react

インストール後、Claude Code で/better-auth-ui-reactを入力して読み込まれたか確認します。

同梱ファイルreferences/shadcn.md

詳細

React 向け Better Auth UI

API のバージョンは、インストール済みパッケージのエクスポートを基準にしてください。このスキルでは、1.7 のパッケージ構成を対象とします。

UI を選択する

  • コピーした shadcn/ui コンポーネントを使う場合は、shadcn の統合を参照してください。
  • パッケージ化された HeroUI コンポーネントを使う場合は、@better-auth-ui/heroui と、利用可能であればその better-auth-ui-heroui スキルを使用してください。
  • カスタムインターフェースを使う場合は、@better-auth-ui/react のプロバイダーとフックを直接使用してください。

@better-auth-ui/react は共有データレイヤーです。コピーされた shadcn の Auth、Settings、UserButton コンポーネントはエクスポートしません。

アプリケーションを設定する

  1. Better Auth を設定し、そのハンドラーをアプリケーションのサーバールートにマウントします。
  2. better-auth/react の createAuthClient で React クライアントを作成します。
  3. 認証関連のコンシューマーを、選択した UI の AuthProvider でラップします。
  4. authClient、ルーター互換の navigate、アプリケーションの queryClient を渡します。
  5. リダイレクト先、UI パス、プラグインをアプリケーションのルートに合わせて設定します。

ナビゲーションコールバックは { to, replace? } を受け取ります。Next.js の router.push と router.replace を直接渡すのではなく、このオブジェクトを受け取る形に適合させてください。

React プロバイダーは、明示的に指定された QueryClient、既存の Query コンテキスト、フォールバックの順に選択します。SSR では、リクエストスコープのクライアントを渡してください。

Next.js では、インタラクティブなプロバイダーとフックにクライアント境界を使用してください。サーバー設定、シークレット、/server のインポートは、それらの境界の外に置いてください。

認証データの読み取りと変更

import { useSession, useSignInEmail } from "@better-auth-ui/react"

const session = useSession(authClient, { staleTime: 5_000 })
const signIn = useSignInEmail(authClient)

これらのフックは、React コンポーネントまたはカスタムフックの中で呼び出してください。認証クライアントを明示的に指定します。

クエリでは、data、isPending、error などの TanStack Query の状態を利用できます。ミューテーションでは、mutate、mutateAsync、isPending を利用できます。

コンシューマー間で Query キャッシュを共有する場合は、Better Auth UI の useSession を使用してください。Better Auth 独自の authClient.useSession() は異なるサブスクリプション経路を使用します。

オプションのフックは @better-auth-ui/react/plugins/<plugin> からインポートします。ローダーファクトリーとヘルパーは、@better-auth-ui/core またはそのプラグインのエントリーポイントからインポートします。

クエリの解決中も、ページの見出し、ナビゲーション、独立したコンテンツはマウントしたままにしてください。未解決の値や、依存するアクションに限って保留状態を表示します。

ローダーと SSR

ブラウザーのローダーには ensureSession(queryClient, authClient) を使用します。サーバーでは @better-auth-ui/core/server の ensureSessionServer(queryClient, auth, { headers }) を使用します。

サーバーリクエストごとに QueryClient を 1 つ作成します。同じクライアントをローダー、ハイドレーション、AuthProvider に渡してください。

TanStack Start では、ドキュメントに記載された Router/Query の SSR 統合を使用します。Next.js では、直接のサーバー呼び出しをサーバー専用コードに置いてください。

1 人のユーザーのセッションを、モジュールレベルのサーバー QueryClient にキャッシュしないでください。ルートガードに加え、サーバーエンドポイントでも権限を検証してください。

プラグインと組織

該当する場合は、各機能を Better Auth サーバー、そのクライアントプラグイン、選択した UI プラグインの 3 か所で有効にしてください。

選択したコンポーネントシステムに付属する UI プラグインを使用します。コアプラグインは共有動作を提供しますが、コピーされた UI ビューは提供しません。

ルート検証には、プラグインのビューパスを含めてください。認証のベースパスをハードコードすると、有効な招待ルートや二要素認証ルートが拒否されることがあります。

ルートのスラッグまたは明示的な ID から組織を選択します。個人アカウントのルートには null を使用し、organizationPlugin({ slug }) を渡してください。

ルートが変わったときは、この値を最新の状態に保ってください。アクセス元として、セッションのアクティブな組織の状態や setActive を使用しないでください。

参考資料

ウェブサイトの例は最新リリースに基づいています。新しいドキュメントに記載された API を使用する前に、インストール済みのパッケージを確認してください。

コメント

Markdown 対応