tanstack-query

Name: tanstack-query
Author: DeckardGer

199stars18forks

How to install tanstack-query?

deckardger/tanstack-agent-skills/tanstack-query

$npx -y skills add DeckardGer/tanstack-agent-skills --skill tanstack-query

Installs into the current project.

Summary

TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.

Files · 1

View on GitHub

SKILL.md

1	# TanStack Query Best Practices
2
3	Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
4
5	## When to Apply
6
7	- Creating new data fetching logic
8	- Setting up query configurations
9	- Implementing mutations and optimistic updates
10	- Configuring caching strategies
11	- Integrating with SSR/SSG
12	- Refactoring existing data fetching code
13
14	## Rule Categories by Priority
15
16	\| Priority \| Category \| Rules \| Impact \|
17	\|----------\|----------\|-------\|--------\|
18	\| CRITICAL \| Query Keys \| 5 rules \| Prevents cache bugs and data inconsistencies \|
19	\| CRITICAL \| Caching \| 5 rules \| Optimizes performance and data freshness \|
20	\| HIGH \| Mutations \| 6 rules \| Ensures data integrity and UI consistency \|
21	\| HIGH \| Error Handling \| 3 rules \| Prevents poor user experiences \|
22	\| MEDIUM \| Prefetching \| 4 rules \| Improves perceived performance \|
23	\| MEDIUM \| Parallel Queries \| 2 rules \| Enables dynamic parallel fetching \|
24	\| MEDIUM \| Infinite Queries \| 3 rules \| Prevents pagination bugs \|
25	\| MEDIUM \| SSR Integration \| 4 rules \| Enables proper hydration \|
26	\| LOW \| Performance \| 4 rules \| Reduces unnecessary re-renders \|
27	\| LOW \| Offline Support \| 2 rules \| Enables offline-first patterns \|
28
29	## Quick Reference
30
31	### Query Keys (Prefix: `qk-`)
32
33	- `qk-array-structure` — Always use arrays for query keys
34	- `qk-include-dependencies` — Include all variables the query depends on
35	- `qk-hierarchical-organization` — Organize keys hierarchically (entity → id → filters)
36	- `qk-factory-pattern` — Use query key factories for complex applications
37	- `qk-serializable` — Ensure all key parts are JSON-serializable
38
39	### Caching (Prefix: `cache-`)
40
41	- `cache-stale-time` — Set appropriate staleTime based on data volatility
42	- `cache-gc-time` — Configure gcTime for inactive query retention
43	- `cache-defaults` — Set sensible defaults at QueryClient level
44	- `cache-invalidation` — Use targeted invalidation over broad patterns
45	- `cache-placeholder-vs-initial` — Understand placeholder vs initial data differences
46
47	### Mutations (Prefix: `mut-`)
48
49	- `mut-invalidate-queries` — Always invalidate related queries after mutations
50	- `mut-optimistic-updates` — Implement optimistic updates for responsive UI
51	- `mut-rollback-context` — Provide rollback context from onMutate
52	- `mut-error-handling` — Handle mutation errors gracefully
53	- `mut-loading-states` — Use isPending for mutation loading states
54	- `mut-mutation-state` — Use useMutationState for cross-component tracking
55
56	### Error Handling (Prefix: `err-`)
57
58	- `err-error-boundaries` — Use error boundaries with useQueryErrorResetBoundary
59	- `err-retry-config` — Configure retry logic appropriately
60	- `err-fallback-data` — Provide fallback data when appropriate
61
62	### Prefetching (Prefix: `pf-`)
63
64	- `pf-intent-prefetch` — Prefetch on user intent (hover, focus)
65	- `pf-route-prefetch` — Prefetch data during route transitions
66	- `pf-stale-time-config` — Set staleTime when prefetching
67	- `pf-ensure-query-data` — Use ensureQueryData for conditional prefetching
68
69	### Infinite Queries (Prefix: `inf-`)
70
71	- `inf-page-params` — Always provide getNextPageParam
72	- `inf-loading-guards` — Check isFetchingNextPage before fetching more
73	- `inf-max-pages` — Consider maxPages for large datasets
74
75	### SSR Integration (Prefix: `ssr-`)
76
77	- `ssr-dehydration` — Use dehydrate/hydrate pattern for SSR
78	- `ssr-client-per-request` — Create QueryClient per request
79	- `ssr-stale-time-server` — Set higher staleTime on server
80	- `ssr-hydration-boundary` — Wrap with HydrationBoundary
81
82	### Parallel Queries (Prefix: `parallel-`)
83
84	- `parallel-use-queries` — Use useQueries for dynamic parallel queries
85	- `query-cancellation` — Implement query cancellation properly
86
87	### Performance (Prefix: `perf-`)
88
89	- `perf-select-transform` — Use select to transform/filter data
90	- `perf-structural-sharing` — Leverage structural sharing
91	- `perf-notify-change-props` — Limit re-renders with notifyOnChangeProps
92	- `perf-placeholder-data` — Use placeholderData for instant UI
93
94	### Offline Support (Prefix: `offline-`)
95
96	- `network-mode` — Configure network mode for offline support
97	- `persist-queries` — Configure query persistence for offline support
98
99	## How to Use
100
101	Each rule file in the `rules/` directory contains:
102	1. Explanation — Why this pattern matters
103	2. Bad Example — Anti-pattern to avoid
104	3. Good Example — Recommended implementation
105	4. Context — When to apply or skip this rule
106
107	## Full Reference
108
109	See individual rule files in `rules/` directory for detailed guidance and code examples.

People who liked this also viewed

6 picks

Type

tanstack-query

199stars18forks

View on GitHub

How to install tanstack-query?

deckardger/tanstack-agent-skills/tanstack-query

$npx -y skills add DeckardGer/tanstack-agent-skills --skill tanstack-query

Installs into the current project.

Summary

TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.

Files · 1

View on GitHub

SKILL.md

1	# TanStack Query Best Practices
2
3	Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
4
5	## When to Apply
6
7	- Creating new data fetching logic
8	- Setting up query configurations
9	- Implementing mutations and optimistic updates
10	- Configuring caching strategies
11	- Integrating with SSR/SSG
12	- Refactoring existing data fetching code
13
14	## Rule Categories by Priority
15
16	\| Priority \| Category \| Rules \| Impact \|
17	\|----------\|----------\|-------\|--------\|
18	\| CRITICAL \| Query Keys \| 5 rules \| Prevents cache bugs and data inconsistencies \|
19	\| CRITICAL \| Caching \| 5 rules \| Optimizes performance and data freshness \|
20	\| HIGH \| Mutations \| 6 rules \| Ensures data integrity and UI consistency \|
21	\| HIGH \| Error Handling \| 3 rules \| Prevents poor user experiences \|
22	\| MEDIUM \| Prefetching \| 4 rules \| Improves perceived performance \|
23	\| MEDIUM \| Parallel Queries \| 2 rules \| Enables dynamic parallel fetching \|
24	\| MEDIUM \| Infinite Queries \| 3 rules \| Prevents pagination bugs \|
25	\| MEDIUM \| SSR Integration \| 4 rules \| Enables proper hydration \|
26	\| LOW \| Performance \| 4 rules \| Reduces unnecessary re-renders \|
27	\| LOW \| Offline Support \| 2 rules \| Enables offline-first patterns \|
28
29	## Quick Reference
30
31	### Query Keys (Prefix: `qk-`)
32
33	- `qk-array-structure` — Always use arrays for query keys
34	- `qk-include-dependencies` — Include all variables the query depends on
35	- `qk-hierarchical-organization` — Organize keys hierarchically (entity → id → filters)
36	- `qk-factory-pattern` — Use query key factories for complex applications
37	- `qk-serializable` — Ensure all key parts are JSON-serializable
38
39	### Caching (Prefix: `cache-`)
40
41	- `cache-stale-time` — Set appropriate staleTime based on data volatility
42	- `cache-gc-time` — Configure gcTime for inactive query retention
43	- `cache-defaults` — Set sensible defaults at QueryClient level
44	- `cache-invalidation` — Use targeted invalidation over broad patterns
45	- `cache-placeholder-vs-initial` — Understand placeholder vs initial data differences
46
47	### Mutations (Prefix: `mut-`)
48
49	- `mut-invalidate-queries` — Always invalidate related queries after mutations
50	- `mut-optimistic-updates` — Implement optimistic updates for responsive UI
51	- `mut-rollback-context` — Provide rollback context from onMutate
52	- `mut-error-handling` — Handle mutation errors gracefully
53	- `mut-loading-states` — Use isPending for mutation loading states
54	- `mut-mutation-state` — Use useMutationState for cross-component tracking
55
56	### Error Handling (Prefix: `err-`)
57
58	- `err-error-boundaries` — Use error boundaries with useQueryErrorResetBoundary
59	- `err-retry-config` — Configure retry logic appropriately
60	- `err-fallback-data` — Provide fallback data when appropriate
61
62	### Prefetching (Prefix: `pf-`)
63
64	- `pf-intent-prefetch` — Prefetch on user intent (hover, focus)
65	- `pf-route-prefetch` — Prefetch data during route transitions
66	- `pf-stale-time-config` — Set staleTime when prefetching
67	- `pf-ensure-query-data` — Use ensureQueryData for conditional prefetching
68
69	### Infinite Queries (Prefix: `inf-`)
70
71	- `inf-page-params` — Always provide getNextPageParam
72	- `inf-loading-guards` — Check isFetchingNextPage before fetching more
73	- `inf-max-pages` — Consider maxPages for large datasets
74
75	### SSR Integration (Prefix: `ssr-`)
76
77	- `ssr-dehydration` — Use dehydrate/hydrate pattern for SSR
78	- `ssr-client-per-request` — Create QueryClient per request
79	- `ssr-stale-time-server` — Set higher staleTime on server
80	- `ssr-hydration-boundary` — Wrap with HydrationBoundary
81
82	### Parallel Queries (Prefix: `parallel-`)
83
84	- `parallel-use-queries` — Use useQueries for dynamic parallel queries
85	- `query-cancellation` — Implement query cancellation properly
86
87	### Performance (Prefix: `perf-`)
88
89	- `perf-select-transform` — Use select to transform/filter data
90	- `perf-structural-sharing` — Leverage structural sharing
91	- `perf-notify-change-props` — Limit re-renders with notifyOnChangeProps
92	- `perf-placeholder-data` — Use placeholderData for instant UI
93
94	### Offline Support (Prefix: `offline-`)
95
96	- `network-mode` — Configure network mode for offline support
97	- `persist-queries` — Configure query persistence for offline support
98
99	## How to Use
100
101	Each rule file in the `rules/` directory contains:
102	1. Explanation — Why this pattern matters
103	2. Bad Example — Anti-pattern to avoid
104	3. Good Example — Recommended implementation
105	4. Context — When to apply or skip this rule
106
107	## Full Reference
108
109	See individual rule files in `rules/` directory for detailed guidance and code examples.

People who liked this also viewed

6 picks

Type