Start Routing Data

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:

1. explore-codebase — map src/routes/, existing loaders, router.tsx, queryClient wiring
2. research-expert — verify Start API via Context7 /websites/tanstack_start_framework_react
3. mcp__context7__query-docs — confirm loader / ssr / ensureQueryData signatures

After implementation, run 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

Critical Rules

1. Loaders are isomorphic — never touch window/localStorage at loader top level; gate with ssr: false/'data-only' or useEffect.
2. Share queryOptions — define once, pass to BOTH ensureQueryData (loader) and useQuery (component) so the cache key matches.
3. Prefetch via context.queryClient — the loader receives queryClient from router context; do not create a new client.
4. Mutations invalidate — after a server-fn write, call router.invalidate() (loader data) or queryClient.invalidateQueries (Query cache).
5. 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

Templates

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