clerk-react-patterns

React SPA パターン

このスキルでは、Vite／CRA の SPA 向けに @clerk/react を扱います。Next.js では clerk-nextjs-patterns を使用してください。TanStack Start では clerk-tanstack-patterns を使用してください。

何が必要ですか？

タスク	リファレンス
useAuth／useUser／useClerk フック	references/hooks.md
React Router を使った保護されたルート	references/protected-routes.md
カスタムのサインイン／サインアップフォーム	references/custom-flows.md
React Router v6/v7 の統合	references/router-integration.md

リファレンス

リファレンス	説明
references/hooks.md	useAuth、isLoaded ガード
references/protected-routes.md	ProtectedRoute パターン
references/custom-flows.md	useSignIn、useSignUp のフロー
references/router-integration.md	React Router v6/v7 のセットアップ

セットアップ

npm install @clerk/react

.env:

VITE_CLERK_PUBLISHABLE_KEY=pk_...

src/main.tsx:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ClerkProvider } from '@clerk/react'
import App from './App.tsx'

const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
      <App />
    </ClerkProvider>
  </StrictMode>,
)

基本的な考え方

@clerk/react はクライアント専用です。サーバー側の auth() はありません。すべての認証状態はフックから取得します。

• isSignedIn を信頼する前に、isLoaded が true であることを確認する必要があります。必ず isLoaded をチェックしてください
• useClerk() を使うと、signOut、openSignIn、openUserProfile などのメソッドにアクセスできます
• useAuth() の getToken() は、API 呼び出し用のセッション JWT を取得します

最小パターン

import { useAuth } from '@clerk/react'

export function Dashboard() {
  const { isLoaded, isSignedIn, userId } = useAuth()

  if (!isLoaded) return <div>Loading...</div>
  if (!isSignedIn) return <div>Please sign in</div>

  return <div>Hello {userId}</div>
}

保護されたルート（React Router v6/v7）

import { Navigate, Outlet } from 'react-router-dom'
import { useAuth } from '@clerk/react'

export function ProtectedRoute() {
  const { isLoaded, isSignedIn } = useAuth()

  if (!isLoaded) return <div>Loading...</div>
  if (!isSignedIn) return <Navigate to="/sign-in" replace />

  return <Outlet />
}

<Routes>
  <Route element={<ProtectedRoute />}>
    <Route path="/dashboard" element={<Dashboard />} />
    <Route path="/settings" element={<Settings />} />
  </Route>
  <Route path="/sign-in" element={<SignIn />} />
</Routes>

API 呼び出し用のトークン

import { useAuth } from '@clerk/react'

export function DataFetcher() {
  const { getToken } = useAuth()

  async function fetchData() {
    const token = await getToken()
    if (!token) return

    const res = await fetch('/api/data', {
      headers: { Authorization: `Bearer ${token}` },
    })
    return res.json()
  }

  return <button onClick={fetchData}>Load</button>
}

よくある問題

症状	原因	対処方法
isSignedIn が undefined	isLoaded がまだ false	必ず最初に isLoaded をチェックします
ClerkProvider がない	Provider がルートに設定されていない	main.tsx で <App> をラップします
環境変数が未定義	Vite のプレフィックスが間違っている	VITE_CLERK_PUBLISHABLE_KEY を使い、import.meta.env からアクセスします
トークンが null	ユーザーがサインインしていない	getToken() の結果が null でないことを確認します
サインインコンポーネントが空白になる	Provider に publishableKey がない	publishableKey を明示的に渡します

関連項目

• clerk-setup - Clerk の初期インストール
• clerk-custom-ui - カスタムフローと外観
• clerk-orgs - B2B 組織

ドキュメント

React SDK