Tanstack Router

Sorgt für typsicheres, dateibasiertes Routing mit TanStack Router nach den offiziellen Konventionen.

Original-Beschreibung der Autoren: Type-safe routing with TanStack Router v1 for React apps, including file-based routing, loaders, search params validation, auth guards, and TanStack Query integration

Die Regel

---
description: "Type-safe routing with TanStack Router v1 for React apps, including file-based routing, loaders, search params validation, auth guards, and TanStack Query integration"
globs: ["src/routes/**/*", "src/routeTree.gen.ts", "app.config.ts"]
alwaysApply: false
---
You are an expert in TanStack Router v1, React, TypeScript, and type-safe client-side routing.

## Core Principles
- TanStack Router is 100% type-safe — leverage TypeScript generics for params, search params, and loader data
- Prefer file-based routing with `@tanstack/router-vite-plugin` for scalability
- Always define routes with `createFileRoute` or `createRootRoute`
- Route data loading belongs in `loader` functions, not in component `useEffect`
- Search params are first-class — always define their schema with Zod for type safety

## File-Based Route Conventions

src/routes/ __root.tsx ← Root layout index.tsx ← / route posts/ index.tsx ← /posts $postId.tsx ← /posts/:postId (dynamic) _layout.tsx ← Layout route (no path segment) _auth/ ← Pathless auth layout group dashboard.tsx

## Route Definition
```tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => fetchPost(params.postId),
  component: PostComponent,
  errorComponent: ({ error }) => <ErrorBanner message={error.message} />,
  pendingComponent: () => <PostSkeleton />,
})

function PostComponent() {
  const post = Route.useLoaderData()     // type-safe
  const { postId } = Route.useParams()  // type-safe
  return <div>{post.title}</div>
}

Type-Safe Search Params

• Always define search params with Zod and validateSearch
• Access with Route.useSearch() — never read window.location.search directly

const searchSchema = z.object({
  page: z.number().int().min(1).default(1),
  q: z.string().optional(),
})

export const Route = createFileRoute('/search')({
  validateSearch: searchSchema,
  component: SearchPage,
})

Navigation

• Use <Link> for internal navigation — never <a href>
• Always pass typed params and search — the compiler will catch mistakes

<Link to="/posts/$postId" params={{ postId: '123' }}>View Post</Link>

Loaders + TanStack Query Integration

export const Route = createFileRoute('/posts')({
  loader: ({ context: { queryClient } }) =>
    queryClient.ensureQueryData(postsQueryOptions()),
  component: PostsPage,
})

Router Context for Dependency Injection

// __root.tsx
interface RouterContext { queryClient: QueryClient; auth: AuthState }
export const Route = createRootRouteWithContext<RouterContext>()({ component: RootLayout })

// main.tsx
const router = createRouter({ routeTree, context: { queryClient, auth } })

Auth Guards

export const Route = createFileRoute('/_auth/dashboard')({
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
  },
  component: Dashboard,
})

Performance

• Set defaultPreload: 'intent' on router for automatic prefetching on hover/focus
• Use React.lazy for route component code splitting
• Install @tanstack/router-devtools and render <TanStackRouterDevtools /> in development

## So nutzt du sie

Die Regel kopieren (Button oben) oder als Datei herunterladen und im Projekt unter `.cursor/rules/` ablegen — Cursor lädt sie beim nächsten Start automatisch. Ältere Cursor-Versionen lesen alternativ eine einzelne `.cursorrules`-Datei im Projektstamm; dort einfach den Regel-Text ohne den Kopfblock zwischen den `---`-Zeilen einfügen.

Der Regel-Text ist englisch — Cursor versteht ihn unabhängig von der Sprache, in der Sie mit dem Editor chatten.


## Im Detail

TanStack Router ist ein type-safe Client-Side-Router, der Routen, Params und Search-Params vollständig typisiert und den Route-Baum aus der Dateistruktur generiert. Die Cursor-Regel sorgt dafür, dass neue Routen nach diesen Konventionen angelegt werden: file-based Routing, generierte routeTree.gen.ts nicht manuell anfassen, Loader- und Search-Validierung z.B. mit Zod. Sinnvoll für Teams, die von React Router kommen und Ende-zu-Ende-Typsicherheit wollen, weniger relevant für kleine Projekte ohne TypeScript-Fokus.

## Praxis-Tipp

Beim Prompt „neue Route für /produkte/:id anlegen“ direkt die Loader-Typisierung mit Zod mitbestellen, statt sie nachträglich zu ergänzen.

## Lizenz & Quelle

- **Lizenz:** CC0 1.0
- **Quelle:** [PatrickJS/awesome-cursorrules (GitHub)](https://github.com/PatrickJS/awesome-cursorrules)

Lade …