# react-tanstack-router-query
Guides AI assistants on structuring React SPAs with TanStack Router v1 and TanStack Query v5 to fetch data in loaders before rendering.
- rule · `type=rule` · Cursor · ★ 41024
- Author: PatrickJS
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/PatrickJS/awesome-cursorrules/tree/HEAD/rules/react-tanstack-router-query.mdc
- Updated: 2026-05-30
- HTML: https://affpapa.org/en/nevibecode/rules/react-tanstack-router-query
## What it does
The rule guides Cursor to generate React SPA architecture using Vite and TypeScript. Route loaders call `queryClient.ensureQueryData` to populate server state before rendering, which prevents route data spinners. Routing and URL state remain strictly within TanStack Router, while TanStack Query handles caching and mutations.
Code conventions enforce declaring `queryOptions` factories outside components and rule out `useEffect` for data fetching. Search parameters act as the single source of truth for filters and pagination, validated through Zod schemas. Successful mutations update the cache immediately via `setQueryData` before navigating to the target screen.
The rule activates for `src/routes/**/*`, `src/queries/**/*`, `src/lib/router.ts`, and `src/lib/queryClient.ts`. Registering the router via `declare module '@tanstack/react-router'` is mandatory, because TypeScript cannot check route paths and parameters without it.
## Install
### Cursor (native platform)
**Manually: put the files in place**
- File: `.cursor/rules/react-tanstack-router-query.mdc` — Frontmatter: description, globs, alwaysApply
### Claude Code
**Manually: put the files in place**
- File: `.claude/rules/react-tanstack-router-query.md` — The paths frontmatter field limits the files: move globs from the source into paths
### Codex
**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there
### GitHub Copilot
**Manually: put the files in place**
- File: `.github/instructions/react-tanstack-router-query.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo
### Windsurf (Devin Desktop)
**Manually: put the files in place**
- File: `.devin/rules/react-tanstack-router-query.md`
### Cline
**Manually: put the files in place**
- File: `.clinerules/react-tanstack-router-query.md`
Where a file is given instead of a command, copy the files from the source to that path: https://github.com/PatrickJS/awesome-cursorrules/tree/HEAD/rules/react-tanstack-router-query.mdc
## When to use it
- Integrate TanStack Router v1 with TanStack Query v5 without route spinners
- Move data fetching logic out of components into route loaders
- Tie URL search parameters directly to Query cache keys
- Warm the query cache on mutation success before triggering navigation
## Example prompts
- Create route `src/routes/posts/$postId.tsx` with a loader using `postQueryOptions` and render the post.
- Implement a paginated posts list using URL search parameters validated with Zod.
- Add a post creation mutation that warms the cache with `setQueryData` and navigates to the new item.
## Source text · react-tanstack-router-query.mdc · CC0-1.0
Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f47d130631fc5d43.
BEGIN THIRD-PARTY FILE f47d130631fc5d43
````text
---
description: "React SPA with TanStack Router v1 + TanStack Query v5 — the definitive pattern for zero-loading-spinner routing, type-safe URLs, and cache-first data"
globs: ["src/routes/**/*", "src/queries/**/*", "src/lib/router.ts", "src/lib/queryClient.ts"]
alwaysApply: false
---
You are an expert in React, TanStack Router v1, TanStack Query v5, TypeScript, and Vite.
## Architecture
- TanStack Router: routing, URL state, navigation
- TanStack Query: server state, caching, mutations
- Loader = bridge: prefetches into Query cache before render → zero loading spinners for route data
- Components are pure UI: read from Query cache, trigger mutations
## Setup
```ts
// src/lib/queryClient.ts
export const queryClient = new QueryClient({
defaultOptions: { queries: { staleTime: 60_000 } },
})
// src/lib/router.ts
export const router = createRouter({
routeTree,
context: { queryClient },
defaultPreload: 'intent',
defaultPreloadStaleTime: 0,
})
declare module '@tanstack/react-router' {
interface Register { router: typeof router }
}
// src/main.tsx
```
## Query Definitions
```ts
// src/queries/posts.ts
export const postKeys = {
all: ['posts'] as const,
detail: (id: string) => [...postKeys.all, 'detail', id] as const,
list: (f?: PostFilters) => [...postKeys.all, 'list', f] as const,
}
export const postQueryOptions = (id: string) =>
queryOptions({ queryKey: postKeys.detail(id), queryFn: () => fetchPost(id) })
export const postsQueryOptions = (filters?: PostFilters) =>
queryOptions({ queryKey: postKeys.list(filters), queryFn: () => fetchPosts(filters) })
```
## Loader + Component (zero loading state)
```tsx
export const Route = createFileRoute('/posts/$postId')({
loader: ({ context: { queryClient }, params }) =>
queryClient.ensureQueryData(postQueryOptions(params.postId)),
component: PostDetail,
})
function PostDetail() {
const { postId } = Route.useParams()
const { data: post } = useQuery(postQueryOptions(postId)) // always in cache from loader
return