practical-react-query

name	practical-react-query
description	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.
license	MIT
metadata	{"author":"tkdodo"}

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>
  );
}