Critical rules: never touch window/localStorage at loader top level (loaders run on the server too) — gate with ssr: false/'data-only' or useEffect instead; share one queryOptions factory between ensureQueryData (loader) and useQuery (component) so cache keys match; prefetch through the router-context queryClient, never a new one; invalidate loaders/Query cache after every server-function write; and remember ssr only tightens down the route tree, a child can never loosen a parent's ssr: false back to true.
Includes templates for a Query-prefetching route and a selective-SSR route.
Do NOT use this skill for generic TanStack Router/Query API questions — route trees, search params, useQuery/useMutation basics belong to react-expert's react-tanstack-router skill.
TanStack Start — Routing Data
Agent Workflow (MANDATORY)
Before ANY implementation, spawn in parallel:
- fuse-ai-pilot:explore-codebase — map
src/routes/, existing loaders, router.tsx, queryClient wiring
- fuse-ai-pilot:research-expert — verify Start API via Context7
/websites/tanstack_start_framework_react
- mcp__context7__query-docs — confirm loader / ssr / ensureQueryData signatures
After implementation, run fuse-ai-pilot:sniper.
Scope Boundary (READ FIRST)
Generic TanStack Router and TanStack Query — route trees, file-based routing, search-param validation, useQuery/useMutation mechanics, cache config — are covered by react-expert's react-tanstack-router. This skill covers ONLY what is specific to Start:
- Loaders are isomorphic (server on first request, client on navigation)
context.queryClient.ensureQueryData() inside a loader (SSR prefetch + hydration)
- Per-route
ssr: true | false | 'data-only'
- Mutations through server functions +
router.invalidate()
Overview
| Start-specific feature |
Description |
| Isomorphic loader |
Route.loader runs on server (initial) AND client (navigation) — no window at top level |
| Query in loader |
ensureQueryData(queryOptions) prefetches on server, useQuery reads cache in component |
| Selective SSR |
ssr flag per route: full SSR, data-only, or client-only |
| Server-fn mutation |
Call createServerFn handler, then router.invalidate() to refetch loaders |
Critical Rules
- Loaders are isomorphic — never touch
window/localStorage at loader top level; gate with ssr: false/'data-only' or useEffect.
- Share
queryOptions — define once, pass to BOTH ensureQueryData (loader) and useQuery (component) so the cache key matches.
- Prefetch via
context.queryClient — the loader receives queryClient from router context; do not create a new client.
- Mutations invalidate — after a server-fn write, call
router.invalidate() (loader data) or queryClient.invalidateQueries (Query cache).
ssr inherits down and only tightens — a child cannot loosen a parent's ssr: false back to true.
Architecture
src/
├── router.tsx # createRouter({ context: { queryClient } })
├── routes/
│ └── posts.$postId.tsx # loader: ensureQueryData + component: useQuery
└── queries/
└── posts.ts # queryOptions factory (shared loader + component)
→ See query-loader-route.md for the complete route
Reference Guide
Concepts
| Topic |
Reference |
Load when |
| Isomorphic loaders |
isomorphic-loaders.md |
Loader touches browser API or you see hydration mismatch |
| Query in loader |
query-in-loader.md |
Integrating TanStack Query prefetch with a Start loader |
| Selective SSR |
selective-ssr.md |
Disabling/tuning SSR per route |
| Mutations |
mutations.md |
Writing data via server functions and refreshing the UI |
Templates
| Template |
When to Use |
| query-loader-route.md |
Route that prefetches with Query and reads in the component |
| selective-ssr-route.md |
Route needing client-only render or data-only SSR |
Best Practices
DO
- Keep
queryOptions factories in src/queries/ and reuse them loader + component
- Return the
ensureQueryData promise directly from the loader (Start awaits it)
- Use
ssr: 'data-only' when the component needs window but the data should still SSR
DON'T
- Duplicate query keys between loader and component (breaks hydration dedupe)
- Read
localStorage/window at loader top level (loader also runs on the server)
- Re-fetch in
useEffect when the loader already primed the cache
1---2name: start-routing-data3description: Use when loading data in Start routes — isomorphic loaders, TanStack Query in a loader, mutations, or per-route SSR. Do NOT use for generic Router/Query API.4versions:5 "@tanstack/react-start": "^1"6 "@tanstack/react-router": "^1"7 "@tanstack/react-query": "^5"8user-invocable: false9references: references/isomorphic-loaders.md, references/query-in-loader.md, references/selective-ssr.md, references/mutations.md, references/templates/query-loader-route.md, references/templates/selective-ssr-route.md10related-skills: react-tanstack-router, nextjs-tanstack-query11metadata:12 source: https://skillmd.com/skills/fusengine/start-routing-data13---1415<objective>16Covers what is specific to TanStack Start about data loading, on top of generic TanStack Router/Query (route trees, file-based routing, search-param validation, useQuery/useMutation mechanics, cache config — all covered instead by react-expert's react-tanstack-router): isomorphic loaders (server on first request, client on navigation), context.queryClient.ensureQueryData() inside a loader for SSR prefetch + hydration, the per-route ssr flag (true | false | 'data-only'), and mutations through server functions followed by router.invalidate().1718Critical rules: never touch window/localStorage at loader top level (loaders run on the server too) — gate with ssr: false/'data-only' or useEffect instead; share one queryOptions factory between ensureQueryData (loader) and useQuery (component) so cache keys match; prefetch through the router-context queryClient, never a new one; invalidate loaders/Query cache after every server-function write; and remember ssr only tightens down the route tree, a child can never loosen a parent's ssr: false back to true.1920Includes templates for a Query-prefetching route and a selective-SSR route.2122Do NOT use this skill for generic TanStack Router/Query API questions — route trees, search params, useQuery/useMutation basics belong to react-expert's react-tanstack-router skill.23</objective>2425# TanStack Start — Routing Data2627## Agent Workflow (MANDATORY)2829Before ANY implementation, spawn in parallel:30311. **fuse-ai-pilot:explore-codebase** — map `src/routes/`, existing loaders, `router.tsx`, queryClient wiring322. **fuse-ai-pilot:research-expert** — verify Start API via Context7 `/websites/tanstack_start_framework_react`333. **mcp__context7__query-docs** — confirm loader / ssr / ensureQueryData signatures3435After implementation, run **fuse-ai-pilot:sniper**.3637---3839## Scope Boundary (READ FIRST)4041Generic TanStack Router and TanStack Query — route trees, file-based routing, search-param validation, `useQuery`/`useMutation` mechanics, cache config — are covered by **react-expert's `react-tanstack-router`**. This skill covers ONLY what is **specific to Start**:4243- Loaders are **isomorphic** (server on first request, client on navigation)44- `context.queryClient.ensureQueryData()` inside a loader (SSR prefetch + hydration)45- Per-route `ssr: true | false | 'data-only'`46- Mutations through **server functions** + `router.invalidate()`4748---4950## Overview5152| Start-specific feature | Description |53|------------------------|-------------|54| **Isomorphic loader** | `Route.loader` runs on server (initial) AND client (navigation) — no `window` at top level |55| **Query in loader** | `ensureQueryData(queryOptions)` prefetches on server, `useQuery` reads cache in component |56| **Selective SSR** | `ssr` flag per route: full SSR, data-only, or client-only |57| **Server-fn mutation** | Call `createServerFn` handler, then `router.invalidate()` to refetch loaders |5859---6061## Critical Rules62631. **Loaders are isomorphic** — never touch `window`/`localStorage` at loader top level; gate with `ssr: false`/`'data-only'` or `useEffect`.642. **Share `queryOptions`** — define once, pass to BOTH `ensureQueryData` (loader) and `useQuery` (component) so the cache key matches.653. **Prefetch via `context.queryClient`** — the loader receives `queryClient` from router context; do not create a new client.664. **Mutations invalidate** — after a server-fn write, call `router.invalidate()` (loader data) or `queryClient.invalidateQueries` (Query cache).675. **`ssr` inherits down and only tightens** — a child cannot loosen a parent's `ssr: false` back to `true`.6869---7071## Architecture7273```74src/75├── router.tsx # createRouter({ context: { queryClient } })76├── routes/77│ └── posts.$postId.tsx # loader: ensureQueryData + component: useQuery78└── queries/79 └── posts.ts # queryOptions factory (shared loader + component)80```8182→ See [query-loader-route.md](references/templates/query-loader-route.md) for the complete route8384---8586## Reference Guide8788### Concepts8990| Topic | Reference | Load when |91|-------|-----------|-----------|92| **Isomorphic loaders** | [isomorphic-loaders.md](references/isomorphic-loaders.md) | Loader touches browser API or you see hydration mismatch |93| **Query in loader** | [query-in-loader.md](references/query-in-loader.md) | Integrating TanStack Query prefetch with a Start loader |94| **Selective SSR** | [selective-ssr.md](references/selective-ssr.md) | Disabling/tuning SSR per route |95| **Mutations** | [mutations.md](references/mutations.md) | Writing data via server functions and refreshing the UI |9697### Templates9899| Template | When to Use |100|----------|-------------|101| [query-loader-route.md](references/templates/query-loader-route.md) | Route that prefetches with Query and reads in the component |102| [selective-ssr-route.md](references/templates/selective-ssr-route.md) | Route needing client-only render or data-only SSR |103104---105106## Best Practices107108### DO109- Keep `queryOptions` factories in `src/queries/` and reuse them loader + component110- Return the `ensureQueryData` promise directly from the loader (Start awaits it)111- Use `ssr: 'data-only'` when the component needs `window` but the data should still SSR112113### DON'T114- Duplicate query keys between loader and component (breaks hydration dedupe)115- Read `localStorage`/`window` at loader top level (loader also runs on the server)116- Re-fetch in `useEffect` when the loader already primed the cache