clerk-tanstack-patterns

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.md	beforeLoad 身份验证重定向
references/server-functions.md	使用 auth() 的 createServerFn
references/loaders.md	加载器中的身份验证上下文
references/server-setup.md	Vite 和请求中间件设置

设置

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 中，将 CSRF 保护注册在 Clerk 请求中间件之前；然后身份验证会经过两层：

1. 服务端层 — 来自 @clerk/tanstack-react-start/server 的 createServerFn + auth()
2. 路由层 — 路由定义上的 beforeLoad，对未进行身份验证的用户抛出 redirect

这两层都在服务端执行。客户端 Hook（useAuth、useUser）是用于浏览器端的 React Hook。

最简模式

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	使用了 return 而不是 throw	在 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