betterauth-tanstack-convex

Better Auth + Convex + TanStack Start

概要

このスキルでは、Better Auth による認証を Convex バックエンドおよび TanStack Start フレームワークと統合する方法を説明します。インストールから SSR に対応した認証フローまで、セットアップの全手順を取り上げます。

このスキルを使用する場面

• 新しい Convex + TanStack Start プロジェクトで認証をセットアップする場合
• Better Auth の設定に関する問題をトラブルシューティングする場合
• サインアップ、サインイン、サインアウトのフローを実装する場合
• expectAuth: true を使用して SSR 認証を設定する場合
• 認証が必要なサーバー関数を追加する場合
• 認証プロバイダーの階層を理解する場合

クイックリファレンス

必須パッケージ

npm install convex@latest @convex-dev/better-auth
npm install [email protected] --save-exact
npm install @types/node --save-dev

環境変数

Convex デプロイメント（CLI 経由）：

npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
npx convex env set SITE_URL http://localhost:3000

.env.local：

CONVEX_DEPLOYMENT=dev:adjective-animal-123
VITE_CONVEX_URL=https://adjective-animal-123.convex.cloud
VITE_CONVEX_SITE_URL=https://adjective-animal-123.convex.site
VITE_SITE_URL=http://localhost:3000

ファイル構成

ファイル	用途
convex/convex.config.ts	Better Auth コンポーネントを登録します
convex/auth.config.ts	認証プロバイダーを設定します
convex/auth.ts	Better Auth インスタンスと authComponent を作成します
convex/http.ts	認証用 HTTP ルートを登録します
src/lib/auth-client.ts	クライアント側の認証ユーティリティ
src/lib/auth-server.ts	サーバー側の認証ユーティリティ
src/routes/api/auth/$.ts	認証リクエストを Convex にプロキシします
src/routes/__root.tsx	認証プロバイダーのラッパーと SSR トークン

必須インポート

// Client-side
import { authClient } from '~/lib/auth-client'

// Server-side
import { getToken, fetchAuthQuery, fetchAuthMutation } from '~/lib/auth-server'

// Backend
import { authComponent, createAuth } from './auth'

認証チェック（バックエンド）

const user = await authComponent.getAuthUser(ctx)
if (!user) throw new Error("Not authenticated")

expectAuth を使用したサインアウト

expectAuth: true を使用する場合は、サインアウト後にページを再読み込みしてください。

await authClient.signOut({
  fetchOptions: {
    onSuccess: () => location.reload(),
  },
})

重要な設定

Vite SSR バンドル

モジュール解決の問題を避けるため、vite.config.ts で次の設定が必要です。

ssr: {
  noExternal: ['@convex-dev/better-auth'],
}

expectAuth を使用した ConvexQueryClient

シームレスな SSR 認証に必要です。

const convexQueryClient = new ConvexQueryClient(convexUrl, {
  expectAuth: true,
})

プロバイダーの階層

ルートコンポーネントでは、次の順序で子要素をラップする必要があります。

1. ConvexBetterAuthProvider（最外層）
2. QueryClientProvider
3. <Outlet /> を含む RootDocument

リファレンスファイル

認証を実装する際は、詳細なセットアップガイドを参照してください。

ファイル	使用する場面
references/setup-guide.md	インストールと設定の全手順