> **clerk-tanstack-patterns** — chapter 18 of 22 in [clerk/skills](https://skillsdocs.com/clerk/skills).
>
> Book (all chapters, one file): https://skillsdocs.com/clerk/skills.md
> Machine manifest: https://skillsdocs.com/clerk/skills/.well-known/agent-skills/index.json
> Install the book: `npx skills add clerk/skills`
> Upstream: https://github.com/clerk/skills/blob/main/skills/frameworks/clerk-tanstack-patterns/SKILL.md @ `main`
> Raw bytes, no header: https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/SKILL.md
> Base for relative paths: https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/
> Licence: MIT — https://spdx.org/licenses/MIT.html
>
> Bundled files (12), referenced from this skill's directory:
>   - `evals/evals.json` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/evals/evals.json
>   - `references/loaders.md` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/references/loaders.md
>   - `references/router-guards.md` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/references/router-guards.md
>   - `references/server-functions.md` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/references/server-functions.md
>   - `references/vinxi-server.md` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/references/vinxi-server.md
>   - `templates/tanstack-basic-auth/package.json` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/templates/tanstack-basic-auth/package.json
>   - `templates/tanstack-basic-auth/src/router.tsx` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/templates/tanstack-basic-auth/src/router.tsx
>   - `templates/tanstack-basic-auth/src/routes/__root.tsx` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/templates/tanstack-basic-auth/src/routes/__root.tsx
>   - `templates/tanstack-basic-auth/src/routes/index.tsx` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/templates/tanstack-basic-auth/src/routes/index.tsx
>   - `templates/tanstack-basic-auth/src/start.ts` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/templates/tanstack-basic-auth/src/start.ts
>   - `templates/tanstack-basic-auth/tsconfig.json` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/templates/tanstack-basic-auth/tsconfig.json
>   - `templates/tanstack-basic-auth/vite.config.ts` — https://raw.githubusercontent.com/clerk/skills/main/skills/frameworks/clerk-tanstack-patterns/templates/tanstack-basic-auth/vite.config.ts
>
> Content © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: clerk-tanstack-patterns
description: 'TanStack React Start auth patterns with @clerk/tanstack-react-start
  - createServerFn, beforeLoad guards, loaders, Vinxi server. Triggers on: TanStack
  auth, createServerFn clerk, beforeLoad protection, TanStack Start middleware.'
license: MIT
allowed-tools: WebFetch
metadata:
  author: clerk
  version: 1.0.0
---

# TanStack React Start Patterns

## What Do You Need?

| Task | Reference |
|------|-----------|
| Protect routes with beforeLoad | references/router-guards.md |
| Auth in createServerFn | references/server-functions.md |
| Pass auth to loaders | references/loaders.md |
| Configure Vinxi + clerkMiddleware | references/vinxi-server.md |

## References

| Reference | Description |
|-----------|-------------|
| `references/router-guards.md` | beforeLoad auth redirect |
| `references/server-functions.md` | createServerFn with auth() |
| `references/loaders.md` | Auth context in loaders |
| `references/vinxi-server.md` | clerkMiddleware() setup |

## Setup

```
npm install @clerk/tanstack-react-start
```

`.env`:
```
CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
```

`src/start.ts` (Vinxi entry):
```typescript
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>`:
```tsx
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

```typescript
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

| Symptom | Cause | Fix |
|---------|-------|-----|
| `auth()` returns empty | Missing `clerkMiddleware` in start.ts | Add to `requestMiddleware` array |
| `redirect` not thrown | Using `return` instead of `throw` | `throw redirect(...)` in TanStack |
| Wrong import for `auth` | Mixing client/server imports | Server: `@clerk/tanstack-react-start/server` |
| Loader context missing userId | Not passing from beforeLoad | Return from beforeLoad, access via `context` |
| `ClerkProvider` missing | Forgot root wrapping | Add to `__root.tsx` shell component |

## See Also

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

## Docs

[TanStack React Start SDK](https://clerk.com/docs/tanstack-react-start/getting-started/quickstart)