Modèles TanStack React Start

De quoi avez-vous besoin ?

Tâche	Référence
Protéger les routes avec beforeLoad	references/router-guards.md
Auth dans createServerFn	references/server-functions.md
Passer auth aux loaders	references/loaders.md
Configurer Vinxi + clerkMiddleware	references/vinxi-server.md

Références

Référence	Description
`references/router-guards.md`	Redirection beforeLoad auth
`references/server-functions.md`	createServerFn avec auth()
`references/loaders.md`	Contexte Auth dans les loaders
`references/vinxi-server.md`	Configuration de clerkMiddleware()

Installation

npm install @clerk/tanstack-react-start

.env :

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

src/start.ts (entrée Vinxi) :

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 — envelopper avec <ClerkProvider> :

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

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

Modèle Mental

TanStack Start s'exécute sur Vinxi. Le flux d'authentification traverse deux couches :

Couche serveur — createServerFn + auth() de @clerk/tanstack-react-start/server
Couche routeur — beforeLoad sur les définitions de routes, lève redirect pour les non-authentifiés

Les deux couches s'exécutent côté serveur. Les hooks client (useAuth, useUser) sont des hooks React pour le côté navigateur.

Modèle Minimal

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

Pièges Courants

Symptôme	Cause	Solution
`auth()` retourne vide	`clerkMiddleware` manquant dans start.ts	Ajouter à l'array `requestMiddleware`
`redirect` non levé	Utiliser `return` au lieu de `throw`	`throw redirect(...)` dans TanStack
Import incorrect pour `auth`	Mélanger imports client/serveur	Serveur : `@clerk/tanstack-react-start/server`
Contexte loader sans userId	Non passé depuis beforeLoad	Retourner depuis beforeLoad, accéder via `context`
`ClerkProvider` manquant	Oubli du wrapping racine	Ajouter au composant shell `__root.tsx`

Voir aussi

clerk-setup - Installation initiale de Clerk
clerk-custom-ui - Flux personnalisés et apparence
clerk-orgs - Organisations B2B

Docs

SDK TanStack React Start

clerk-tanstack-patterns