cloudvoyant/tanstack

tanstack

Recipes for building React apps on TanStack Start (Router v1 + Query v5 + Form + createServerFn). Targets React 19, Vite 7-8, Nitro 3 SSR.

When to load recipes

| You are working on… | Load recipe | |---|---| | New TanStack Start project (deps, vite, tsconfig, entries) | references/recipes/project-setup.md | | Route files, root route, loaders, search params, API routes | references/recipes/router.md | | Server functions (createServerFn) with Zod + middleware | references/recipes/server-actions.md | | Auth-gated route subtrees (loader redirect or provider gate) | references/recipes/auth-routes.md | | useQuery / useMutation / useInfiniteQuery + TanStack Form | references/recipes/query-and-forms.md |

Load project-setup + router together when scaffolding a new TanStack Start app.

Core Conventions

• tanstackStart() Vite plugin owns SSR entry and generates src/routeTree.gen.ts — never edit the gen file, never add @tanstack/router-plugin to the vite config separately
• Plugin order in vite.config.ts: [tanstackStart(), nitro(), react(), svgr(), tailwindcss()]
• Path alias ~/* -> src/* via resolve: { tsconfigPaths: true } or vite-tsconfig-paths
• Root route uses createRootRouteWithContext<{ queryClient: QueryClient }>() with ssr: "data-only", separate shellComponent (HTML document) and component (provider tree)
• Single QueryClient defaults block reused everywhere: staleTime: 1000 * 20, refetchOnWindowFocus: false, retry: 1
• Server-only modules (DB drivers, secret-reading helpers) imported dynamically inside loaders (await import("@acme/db")) to stay out of the client bundle
• Server functions chain: createServerFn({ method }).middleware([...]).inputValidator(zod).handler(async (ctx) => ...) — input on ctx.data, middleware values on ctx.context
• Env split: PUBLIC_* surfaced via a server fn read in the root loader; PRIVATE_* server-only
• Query keys come from typed as const factories; mutations invalidate by key in onSettled

Common Pitfalls

• Always pass queryClient via router context — otherwise loaders cannot share cache with components
• Set defaultPreloadStaleTime: 0 on the router so react-query owns staleness (avoids double-caching)
• Never read search directly in loader — use loaderDeps so preload/dedupe works
• Use useSuspenseQuery in components when a loader prefetched the same queryOptions — synchronous, no isPending branch
• TanStack Form async validators must use onChangeAsync / onSubmitAsync (not onChange / onSubmit) or TS swallows the promise
• routeTree.gen.ts is generated by tanstackStart() on dev/build — commit it only if the plugin does not run in CI