TanStack Router Cursor Rules

What it does

TanStack Router markets itself as “100% type-safe” — that promise is only real if models wire routes through createFileRoute, validate search params with Zod, and put data fetching in loader functions instead of useEffect. Without scoped rules, models default to React Router idioms (<BrowserRouter>, useParams() with string | undefined) and break that guarantee.

This rule set covers file-based routing conventions, type-safe search params, route loaders with TanStack Query integration, beforeLoad auth guards, error/pending/notFound components, and performance preloading.

Sourced from PatrickJS/awesome-cursorrules.

The rules

# TanStack Router + React Guidelines

## Core Philosophy
- TanStack Router is 100% type-safe — leverage TypeScript generics for route params, search params, and loader data
- Prefer file-based routing for scalability; use code-based routing only for highly dynamic use cases
- Always define routes with `createFileRoute` or `createRootRoute` — never use plain objects
- Route data loading belongs in `loader` functions, not in component `useEffect`
- Search params are first-class citizens — define their schema with Zod or Valibot

## Project Setup
- Use `@tanstack/react-router` with Vite and the `@tanstack/router-vite-plugin` for file-based routing
- Enable `routeTree.gen.ts` auto-generation — never manually edit this file
- Structure routes under `src/routes/` directory
- Root layout goes in `src/routes/__root.tsx`
- Use `src/routes/index.tsx` for the home/index route

## Type-Safe Search Params
- Always define search param schemas using `z.object()` from Zod
- Use `validateSearch` option on route definition
- Access with `Route.useSearch()` — never read raw `window.location.search`

## Loaders & Data Fetching
- Use `loader` for data that must be available before render
- Integrate with TanStack Query by using `ensureQueryData` inside loaders for caching
- Return plain serializable data from loaders — no class instances

## Route Guards / Auth
- Use `beforeLoad` for authentication checks — redirect to login if unauthenticated
- Never put auth logic inside components — handle it at the routing layer

## Performance
- Use `preload` on `<Link>` to trigger loader prefetching on hover/focus
- Set `defaultPreload: 'intent'` on the router for automatic preloading

Installation

Create .cursor/rules/tanstack-router.mdc in your project root:

mkdir -p .cursor/rules
curl -o .cursor/rules/tanstack-router.mdc \
  https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/tanstack-router-react-cursorrules-prompt-file.mdc

Or copy the full file from the awesome-cursorrules repo into .cursor/rules/.

Why it helps

Without these rules, models will:

• Use React Router idioms (<BrowserRouter>, useParams()) and lose end-to-end type safety
• Fetch data in useEffect, causing loading spinners on critical pages
• Read window.location.search directly instead of validating search params
• Put auth checks inside components rather than at the routing layer
• Edit routeTree.gen.ts by hand and break route generation