mcpField
C
clerk-tanstack-patterns

clerk-tanstack-patterns

github.com/clerk開発8915.7k 回インストール今日更新
リポジトリ

clerk-tanstack-patterns について

TanStack React Start に Clerk 認証を組み込む開発者向けのパターン集です。サーバー関数やルートでの認証処理、ミドルウェア設定を扱います。

主な機能

  1. 01認証付きルートガードとリダイレクト
  2. 02サーバー関数での認証状態取得
  3. 03ローダーへの認証コンテキスト受け渡し
  4. 04Vite と Clerk ミドルウェアの設定

活用シーン

  1. 01サインイン必須ルートの保護
  2. 02サーバー関数でのユーザー確認
  3. 03ルートローダーへの userId 受け渡し

インストール

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

$npx skills add https://github.com/clerk/skills --skill clerk-tanstack-patterns

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
evals.json
references/
loaders.md
router-guards.md
server-functions.md
server-setup.md
templates/tanstack-basic-auth/
package.json
tsconfig.json
vite.config.ts
templates/tanstack-basic-auth/src/
router.tsx
start.ts
templates/tanstack-basic-auth/src/routes/
__root.tsx
index.tsx

詳細

TanStack React Start のパターン

必要な情報はどれですか？

タスクリファレンス
beforeLoad でルートを保護するreferences/router-guards.md
createServerFn で認証するreferences/server-functions.md
ローダーに認証情報を渡すreferences/loaders.md
Vite と Clerk ミドルウェアを設定するreferences/server-setup.md

リファレンス

リファレンス説明
references/router-guards.mdbeforeLoad による認証リダイレクト
references/server-functions.mdauth() を使った createServerFn
references/loaders.mdローダーの認証コンテキスト
references/server-setup.mdVite とリクエストミドルウェアの設定

セットアップ

npm install @clerk/tanstack-react-start

.env:

VITE_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

src/start.ts（リクエストミドルウェア）:

import { clerkMiddleware } from '@clerk/tanstack-react-start/server'
import { createCsrfMiddleware, createStart } from '@tanstack/react-start'

const csrfMiddleware = createCsrfMiddleware({
  filter: (ctx) => ctx.handlerType === 'serverFn',
})

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [csrfMiddleware, clerkMiddleware()],
  }
})

src/routes/__root.tsx — <ClerkProvider> でラップします:

import { ClerkProvider } from '@clerk/tanstack-react-start'

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClerkProvider>
          {children}
        </ClerkProvider>
      </body>
    </html>
  )
}

基本的な考え方

TanStack Start は tanstackStart() Vite プラグインを使用します。src/start.ts では Clerk リクエストミドルウェアより前に CSRF 保護を登録します。認証は次の 2 つのレイヤーを通じて行われます。

  1. サーバーレイヤー — @clerk/tanstack-react-start/server の createServerFn と auth()
  2. ルーターレイヤー — ルート定義の beforeLoad。未認証の場合は redirect をスローします

どちらのレイヤーもサーバー上で実行されます。クライアントフック（useAuth、useUser）はブラウザー側で使用する React フックです。

最小限のパターン

import { createFileRoute, redirect } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'
import { auth } from '@clerk/tanstack-react-start/server'

const authStateFn = createServerFn().handler(async () => {
  const { isAuthenticated, userId } = await auth()
  if (!isAuthenticated) {
    throw redirect({ to: '/sign-in' })
  }
  return { userId }
})

export const Route = createFileRoute('/dashboard')({
  beforeLoad: async () => await authStateFn(),
})

よくある問題

症状原因対処法
auth() が「without configuring the middleware」エラーをスローするstart.ts に clerkMiddleware がないrequestMiddleware の CSRF ミドルウェアの後に追加します
redirect がスローされないthrow ではなく return を使用しているTanStack では throw redirect(...) を使用します
auth のインポート先が違うクライアントとサーバーのインポートが混在しているサーバー: @clerk/tanstack-react-start/server
ローダーのコンテキストに userId がないbeforeLoad から渡していないbeforeLoad から返し、context 経由でアクセスします
ClerkProvider がないルートのラップを忘れているシェルコンポーネントの __root.tsx に追加します

関連項目

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

ドキュメント

TanStack React Start SDK

コメント

Markdown 対応