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. 04配置 Vite 与 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.md使用 auth() 的 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 中，将 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

评论

支持 Markdown