React Query Guide
This skill provides comprehensive guidance on React Query (TanStack Query) for building modern React applications with async state management.
When to Use This Skill
Use this skill when you need help with:
- Setting up and configuring React Query
- Data fetching, caching, and synchronization
- Mutations and optimistic updates
- Error handling and retry strategies
- TypeScript integration
- Testing React Query code
- Performance optimization
- Advanced patterns and best practices
Topics
Read the relevant reference file based on what you need:
Getting Started
| Topic |
Description |
File |
| Practical React Query |
Core concepts, defaults, query keys, custom hooks |
01-practical-react-query.md |
| Why Use React Query |
Benefits and reasons to adopt React Query |
23-why-use.md |
| When Not Needed |
Simpler alternatives when React Query is overkill |
21-when-not-needed.md |
Core Concepts
| Topic |
Description |
File |
| Query Keys |
Structuring keys for caching, refetching, invalidation |
08-query-keys.md |
| Query Function Context |
Extract params from query keys |
09-query-function-context.md |
| Query Options API |
Code organization and type inference |
24-query-options-api.md |
| State Manager |
React Query as an async state manager |
11-state-manager.md |
Data Handling
| Topic |
Description |
File |
| Data Transformations |
Transform data in queryFn, render, or select |
02-data-transformations.md |
| Placeholder & Initial Data |
Pre-fill cache, improve UX |
10-placeholder-initial-data.md |
| Seeding Cache |
Pre-populate query cache |
18-seeding-cache.md |
| Selectors |
Advanced selector patterns for partial subscriptions |
28-selectors.md |
Mutations & Updates
| Topic |
Description |
File |
| Mutations |
useMutation, optimistic updates, invalidation |
13-mutations.md |
| Auto Invalidation |
Automatic query invalidation patterns |
25-auto-invalidation.md |
| Concurrent Optimistic Updates |
Handle concurrent optimistic updates |
27-concurrent-optimistic.md |
State & Error Handling
| Topic |
Description |
File |
| Status Checks |
Loading states, background errors |
04-status-checks.md |
| Error Handling |
Error boundaries, retry strategies |
12-error-handling.md |
Performance
| Topic |
Description |
File |
| Render Optimizations |
notifyOnChangeProps, tracked queries, structural sharing |
03-render-optimizations.md |
| Infinite Queries |
Pagination, infinite scroll |
26-infinite-queries.md |
Integration
| Topic |
Description |
File |
| TypeScript |
Generics, type narrowing, enabled option typing |
06-typescript.md |
| Type Safety |
Advanced TypeScript patterns |
20-type-safe.md |
| React Router |
Data loading, navigation integration |
17-react-router.md |
| React Context |
Combining with React Context |
22-context.md |
| WebSockets |
Real-time data sync |
07-websockets.md |
| Forms |
Form integration, handling form state |
15-forms.md |
Advanced
| Topic |
Description |
File |
| Internals |
QueryClient, QueryCache, QueryObserver |
19-internals.md |
| Offline Support |
Persistence, offline mutations |
14-offline.md |
| Testing |
Mocking network requests, MSW integration |
05-testing.md |
| FAQs |
Frequently asked questions |
16-faqs.md |
Quick Reference
Basic Query
import { useQuery } from "@tanstack/react-query";
function Component() {
const { data, isLoading, error } = useQuery({
queryKey: ["todos"],
queryFn: fetchTodos,
});
}
Basic Mutation
import { useMutation, useQueryClient } from "@tanstack/react-query";
function Component() {
const queryClient = useQueryClient();
const mutation = useMutation({
mutationFn: addTodo,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ["todos"] });
},
});
}
Query Client Setup
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
const queryClient = new QueryClient();
function App() {
return (
<QueryClientProvider client={queryClient}>
<YourApp />
</QueryClientProvider>
);
}
1---2name: practical-react-query3description: Comprehensive guide to React Query (TanStack Query) covering data fetching, caching, mutations, error handling, TypeScript, testing, and advanced patterns. Use when working with React Query, TanStack Query, or async state management in React applications.4license: MIT5---67# React Query Guide89This skill provides comprehensive guidance on React Query (TanStack Query) for building modern React applications with async state management.1011## When to Use This Skill1213Use this skill when you need help with:1415- Setting up and configuring React Query16- Data fetching, caching, and synchronization17- Mutations and optimistic updates18- Error handling and retry strategies19- TypeScript integration20- Testing React Query code21- Performance optimization22- Advanced patterns and best practices2324## Topics2526Read the relevant reference file based on what you need:2728### Getting Started2930| Topic | Description | File |31| --------------------- | ------------------------------------------------- | ----------------------------------------------------------------- |32| Practical React Query | Core concepts, defaults, query keys, custom hooks | [01-practical-react-query.md](references/01-practical-react-query.md) |33| Why Use React Query | Benefits and reasons to adopt React Query | [23-why-use.md](references/23-why-use.md) |34| When Not Needed | Simpler alternatives when React Query is overkill | [21-when-not-needed.md](references/21-when-not-needed.md) |3536### Core Concepts3738| Topic | Description | File |39| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |40| Query Keys | Structuring keys for caching, refetching, invalidation | [08-query-keys.md](references/08-query-keys.md) |41| Query Function Context | Extract params from query keys | [09-query-function-context.md](references/09-query-function-context.md) |42| Query Options API | Code organization and type inference | [24-query-options-api.md](references/24-query-options-api.md) |43| State Manager | React Query as an async state manager | [11-state-manager.md](references/11-state-manager.md) |4445### Data Handling4647| Topic | Description | File |48| -------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------- |49| Data Transformations | Transform data in queryFn, render, or select | [02-data-transformations.md](references/02-data-transformations.md) |50| Placeholder & Initial Data | Pre-fill cache, improve UX | [10-placeholder-initial-data.md](references/10-placeholder-initial-data.md) |51| Seeding Cache | Pre-populate query cache | [18-seeding-cache.md](references/18-seeding-cache.md) |52| Selectors | Advanced selector patterns for partial subscriptions | [28-selectors.md](references/28-selectors.md) |5354### Mutations & Updates5556| Topic | Description | File |57| ----------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |58| Mutations | useMutation, optimistic updates, invalidation | [13-mutations.md](references/13-mutations.md) |59| Auto Invalidation | Automatic query invalidation patterns | [25-auto-invalidation.md](references/25-auto-invalidation.md) |60| Concurrent Optimistic Updates | Handle concurrent optimistic updates | [27-concurrent-optimistic.md](references/27-concurrent-optimistic.md) |6162### State & Error Handling6364| Topic | Description | File |65| -------------- | ---------------------------------- | --------------------------------------------------- |66| Status Checks | Loading states, background errors | [04-status-checks.md](references/04-status-checks.md) |67| Error Handling | Error boundaries, retry strategies | [12-error-handling.md](references/12-error-handling.md) |6869### Performance7071| Topic | Description | File |72| -------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |73| Render Optimizations | notifyOnChangeProps, tracked queries, structural sharing | [03-render-optimizations.md](references/03-render-optimizations.md) |74| Infinite Queries | Pagination, infinite scroll | [26-infinite-queries.md](references/26-infinite-queries.md) |7576### Integration7778| Topic | Description | File |79| ------------- | ----------------------------------------------- | ----------------------------------------------- |80| TypeScript | Generics, type narrowing, enabled option typing | [06-typescript.md](references/06-typescript.md) |81| Type Safety | Advanced TypeScript patterns | [20-type-safe.md](references/20-type-safe.md) |82| React Router | Data loading, navigation integration | [17-react-router.md](references/17-react-router.md) |83| React Context | Combining with React Context | [22-context.md](references/22-context.md) |84| WebSockets | Real-time data sync | [07-websockets.md](references/07-websockets.md) |85| Forms | Form integration, handling form state | [15-forms.md](references/15-forms.md) |8687### Advanced8889| Topic | Description | File |90| --------------- | ----------------------------------------- | ----------------------------------------- |91| Internals | QueryClient, QueryCache, QueryObserver | [19-internals.md](references/19-internals.md) |92| Offline Support | Persistence, offline mutations | [14-offline.md](references/14-offline.md) |93| Testing | Mocking network requests, MSW integration | [05-testing.md](references/05-testing.md) |94| FAQs | Frequently asked questions | [16-faqs.md](references/16-faqs.md) |9596## Quick Reference9798### Basic Query99100```tsx101import { useQuery } from "@tanstack/react-query";102103function Component() {104 const { data, isLoading, error } = useQuery({105 queryKey: ["todos"],106 queryFn: fetchTodos,107 });108}109```110111### Basic Mutation112113```tsx114import { useMutation, useQueryClient } from "@tanstack/react-query";115116function Component() {117 const queryClient = useQueryClient();118119 const mutation = useMutation({120 mutationFn: addTodo,121 onSuccess: () => {122 queryClient.invalidateQueries({ queryKey: ["todos"] });123 },124 });125}126```127128### Query Client Setup129130```tsx131import { QueryClient, QueryClientProvider } from "@tanstack/react-query";132133const queryClient = new QueryClient();134135function App() {136 return (137 <QueryClientProvider client={queryClient}>138 <YourApp />139 </QueryClientProvider>140 );141}142```