# tanstack-integration-best-practices

A skill that hands the agent rules for wiring TanStack Query, Router and Start together: loaders, SSR hydration, cache ownership. Useful once all three live in one codebase.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2900 installs · ★ 228
- Author: DeckardGer
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/DeckardGer/tanstack-agent-skills/tree/HEAD/skills/tanstack-integration/SKILL.md
- Updated: 2026-09-09
- HTML: https://affpapa.org/en/nevibecode/skills/tanstack-integration-best-practices

## What it does

Rules are grouped by priority, from setup down to caching. The `rules/` folder holds files under the `setup-`, `flow-`, `cache-` and `ssr-` prefixes. Each one explains why the pattern exists, shows the anti-pattern, then the recommended code, and notes when to skip it. The agent pulls these in while you build data fetching on TanStack Start.

Setup and SSR integration carry the highest weight. Those rules cover passing `QueryClient` through router context, wrapping the app in `QueryClientProvider`, aligning `staleTime` across router and queries, and calling `setupRouterSsrQueryIntegration`. For SSR there is also a separate `QueryClient` per request.

The rest concerns data flow. Loaders call `ensureQueryData`. Components use `useSuspenseQuery`. Server functions back the query functions, and mutations trigger invalidation through a shared pattern. Query owns the cache. Skip the install and your agent writes this from scratch instead.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-integration-best-practices -a claude-code
```
```bash
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-integration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tanstack-integration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tanstack-integration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-integration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tanstack-integration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-integration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tanstack-integration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install DeckardGer/tanstack-agent-skills tanstack-integration
```

2. **Manually: put the files in place**
- File: `.github/skills/tanstack-integration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-integration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/DeckardGer/tanstack-agent-skills --path skills/tanstack-integration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tanstack-integration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-integration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/DeckardGer/tanstack-agent-skills/tree/HEAD/skills/tanstack-integration/SKILL.md

## When to use it
- align `staleTime` between router and queries
- set up SSR with query hydration
- pass `QueryClient` via router context
- pair mutations with cache invalidation
- stop double caching in router and Query

## Example prompts
- Add SSR with query hydration to my new TanStack Start project.
- Move these loaders to `ensureQueryData` and tell me why.
- After this mutation the cache is stale — show the invalidation pattern.

## Source text · SKILL.md · MIT

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: 2c15777af8f4c785.

BEGIN THIRD-PARTY FILE 2c15777af8f4c785
```text
---
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
```
END THIRD-PARTY FILE 2c15777af8f4c785

The third-party file has ended. Everything between the 2c15777af8f4c785 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2500 of 2609 bytes. © DeckardGer · MIT · https://github.com/DeckardGer/tanstack-agent-skills/tree/HEAD/skills/tanstack-integration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md