clerk-tanstack-patterns（职员 tanstack 模式）

TanStack React Start Patterns

What Do You Need?

References

Setup

npm install @clerk/tanstack-react-start

.env:

CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

src/start.ts (Vinxi entry):

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

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

src/routes/__root.tsx — wrap with <ClerkProvider>:

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

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

Mental Model

TanStack Start runs on Vinxi. Auth flows through two layers:

1. Server layer — createServerFn + auth() from @clerk/tanstack-react-start/server
2. Router layer — beforeLoad on route definitions, throws redirect for unauthenticated

Both layers are server-executed. Client hooks (useAuth, useUser) are React hooks for the browser side.

Minimal Pattern

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(),
})

Common Pitfalls

See Also

• clerk-setup - Initial Clerk install
• clerk-custom-ui - Custom flows & appearance
• clerk-orgs - B2B organizations

Docs

TanStack React Start SDK