playbooks

home / skills / deckardger / tanstack-agent-skills / tanstack-integration

tanstack-integration skill

/skills/tanstack-integration

This skill helps you implement best practices for integrating TanStack Query, Router, and Start across SSR, caching, and data flow.

npx playbooks add skill deckardger/tanstack-agent-skills --skill tanstack-integration

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.5 KB
---
name: tanstack-integration-best-practices
description: Best practices for integrating TanStack Query with TanStack Router and TanStack Start. Patterns for full-stack data flow, SSR, and caching coordination.
---

# TanStack Integration Best Practices

Guidelines for integrating TanStack Query, Router, and Start together effectively. These patterns ensure optimal data flow, caching coordination, and type safety across the stack.

## When to Apply

- Setting up a new TanStack Start project
- Integrating TanStack Query with TanStack Router
- Configuring SSR with query hydration
- Coordinating caching between router and query
- Setting up type-safe data fetching patterns

## Rule Categories by Priority

| Priority | Category | Rules | Impact |
|----------|----------|-------|--------|
| CRITICAL | Setup | 3 rules | Foundational configuration |
| CRITICAL | SSR Integration | 1 rule | Router + Query SSR setup |
| HIGH | Data Flow | 4 rules | Correct data fetching patterns |
| MEDIUM | Caching | 3 rules | Performance optimization |
| MEDIUM | SSR | 2 rules | Additional SSR patterns |

## Quick Reference

### Setup (Prefix: `setup-`)

- `setup-query-client-context` — Pass QueryClient through router context
- `setup-provider-wrapping` — Correctly wrap with QueryClientProvider
- `setup-stale-time-coordination` — Coordinate staleTime between router and query

### Data Flow (Prefix: `flow-`)

- `flow-loader-query-pattern` — Use loaders with ensureQueryData
- `flow-suspense-query-component` — Use useSuspenseQuery in components
- `flow-mutations-invalidation` — Coordinate mutations with query invalidation
- `flow-server-functions-queries` — Use server functions for query functions

### Caching (Prefix: `cache-`)

- `cache-single-source` — Let TanStack Query manage caching
- `cache-preload-coordination` — Coordinate preloading between router and query
- `cache-invalidation-patterns` — Unified invalidation patterns

### SSR Integration (Prefix: `ssr-`)

- `ssr-dehydrate-hydrate` — Use setupRouterSsrQueryIntegration for automatic SSR

### Additional SSR (Prefix: `ssr-`)

- `ssr-per-request-client` — Create QueryClient per request
- `ssr-streaming-queries` — Handle streaming with queries

## How to Use

Each rule file in the `rules/` directory contains:
1. **Explanation** — Why this pattern matters
2. **Bad Example** — Anti-pattern to avoid
3. **Good Example** — Recommended implementation
4. **Context** — When to apply or skip this rule

## Full Reference

See individual rule files in `rules/` directory for detailed guidance and code examples.

Overview

This skill describes practical best practices for integrating TanStack Query with TanStack Router and TanStack Start. It focuses on full-stack data flow, SSR coordination, and unified caching for predictable client and server behavior. The guidance targets setup, loader/component patterns, and per-request SSR concerns to reduce bugs and improve performance.

How this skill works

The skill inspects integration patterns and provides rules that map to concrete implementation steps like provider wrapping, router-context wiring, and query hydration on SSR. It highlights loader-based fetching, useSuspenseQuery usage, mutation invalidation coordination, and a single source of caching governed by TanStack Query. Each rule bundles rationale, anti-patterns, and recommended code patterns for quick application.

When to use it

  • Starting a new TanStack Start project that will use TanStack Query and Router
  • Integrating client-side routes with server-side rendered data and hydration
  • Coordinating cache and preloading behavior between router loaders and query cache
  • Implementing type-safe data fetching with server functions and query functions
  • Adding streaming or per-request SSR for multi-user server rendering scenarios

Best practices

  • Wrap the app with a single QueryClientProvider and pass QueryClient through the router context to ensure consistent cache access
  • Use loaders with ensureQueryData to populate the query cache during navigation and avoid duplicate fetches
  • Prefer useSuspenseQuery in components for consistent suspense boundaries and to reuse loader-populated data
  • Treat TanStack Query as the single source of truth for caching; avoid duplicating cache logic in the router
  • Create a fresh QueryClient per SSR request and dehydrate/hydrate using the provided integration helpers
  • Coordinate staleTime and preloading strategies between router loaders and query options to prevent unnecessary refetches

Example use cases

  • Hydrate server-rendered pages by running loaders that call ensureQueryData, then dehydrate the QueryClient for the client bundle
  • Implement optimistic updates: run a mutation, invalidate affected queries, and let the query cache refresh UI state
  • Build type-safe route loaders that call server functions for query functions and reuse the same types on client and server
  • Configure streaming SSR for long pages: stream HTML while resolving key query data on the server and hydrating progressively on the client
  • Set up per-request QueryClient for multi-tenant SSR to avoid cross-request cache leakage

FAQ

Do I need a separate cache for the router and Query?

No. Let TanStack Query manage caching; coordinate the router to populate or preload the query cache rather than duplicating state.

How do I avoid duplicate fetches between loaders and components?

Use loaders to call ensureQueryData and have components useSuspenseQuery or standard query hooks so they read from the populated cache instead of refetching.