Learn TanStack Query from first principles through practical examples
This tutorial series takes you from basic data fetching to advanced patterns through hands-on exploration of real examples. Each tutorial is based on a working example from the TanStack Query repository, ensuring you learn practical, battle-tested patterns.
These tutorials follow the Feynman Approach to learning:
- Deconstruct Complexity: Break down each pattern to its fundamental purpose
- Use Intuitive Analogies: Connect abstract concepts to familiar mental models
- Focus on the 'Why': Understand not just how things work, but why they're designed that way
- Assume Intelligence: Dive deep into concepts while explaining clearly
Each tutorial follows a consistent format:
- The Core Concept: Why this pattern exists and what problem it solves
- Practical Walkthrough: Step-by-step code breakdown with explanations
- Mental Model: Deep understanding of the underlying concepts and design principles
Start here to understand TanStack Query's fundamental principles.
Based on:
examples/react/simple
Learn the essential building blocks: QueryClient, useQuery, and the cache-first mindset. Understand why Query transforms traditional data fetching and how the "stale-while-revalidate" strategy creates instant-feeling interfaces.
Key Concepts: Query setup, loading states, cache hits, declarative data fetching
Based on:
examples/react/basic
Explore how Query's intelligent cache manages relationships between different data sets, provides instant navigation between views, and persists data across browser sessions.
Key Concepts: Cache relationships, background updates, persistence, query invalidation
Based on:
examples/react/pagination
Master the art of seamless pagination using keepPreviousData and strategic prefetching. Learn how to eliminate jarring loading states and create fluid browsing experiences.
Key Concepts: Placeholder data, prefetching, pagination strategy, smooth transitions
Build on core concepts with sophisticated data management patterns.
Based on:
examples/react/optimistic-updates-ui
Implement optimistic updates that assume success and show immediate feedback. Learn how to handle failures gracefully while maintaining user confidence and context.
Key Concepts: Optimistic UI, mutation states, error recovery, responsive feedback
Based on:
examples/react/load-more-infinite-scroll
Create buttery-smooth infinite scroll experiences using useInfiniteQuery and modern browser APIs. Understand how to model infinite data as a continuous stream with intelligent caching.
Key Concepts: Infinite queries, cursor pagination, intersection observer, bidirectional loading
Based on:
examples/vue/basic
Discover how TanStack Query integrates seamlessly with Vue's Composition API and reactivity system. Learn Vue-specific patterns for building reactive, cache-aware applications.
Key Concepts: Vue reactivity, composables, component communication, framework integration
Master complex patterns needed for real-world applications.
Based on:
examples/react/default-query-function
Implement convention-over-configuration patterns with default query functions. Learn how to design semantic query keys that drive automatic data fetching across your entire application.
Key Concepts: Convention over configuration, semantic query keys, centralized data fetching, URL patterns
Based on:
examples/react/offline
Build resilient applications that work regardless of network conditions. Master mutation queuing, cache persistence, and graceful degradation for truly robust user experiences.
Key Concepts: Offline-first architecture, mutation queuing, background sync, resilient UI patterns
Advanced tutorials covering cutting-edge React integration patterns.
Based on:
examples/react/auto-refetching
Transform any API into a live, reactive data stream using intelligent polling. Learn how to coordinate real-time updates with user interactions and create applications that naturally stay synchronized with changing backend data.
Key Concepts: Polling strategies, real-time synchronization, cross-tab communication, dynamic intervals
Based on:
examples/react/basic-graphql-request
Combine GraphQL's precise data fetching with TanStack Query's superior caching. Discover how Query's transport-agnostic design enables lightweight GraphQL integration with full type safety and intelligent caching.
Key Concepts: GraphQL integration, type safety, field selection, transport agnostic design
Based on:
examples/react/suspense
Master React's concurrent features with declarative data fetching. Learn how Suspense transforms imperative loading states into elegant boundary components, creating consistent and coordinated user experiences.
Key Concepts: Concurrent React, declarative loading, error boundaries, fetch-as-you-render
Based on:
examples/react/nextjs-app-prefetching
Implement cutting-edge SSR patterns with Next.js App Router and React Server Components. Learn how to prefetch data server-side and seamlessly hydrate to full client-side functionality.
Key Concepts: App Router integration, server components, hydration boundaries, progressive enhancement
Deep-dive tutorials for specialized scenarios and advanced implementations.
Based on:
examples/react/algolia
Build sophisticated search experiences with intelligent debouncing, infinite result loading, and performance optimization. Learn how to coordinate user input, network requests, and result display for responsive search interfaces.
Key Concepts: Search UX, debouncing strategies, infinite search results, performance optimization
Based on:
examples/react/chat
Implement modern chat interfaces with streaming responses that appear word-by-word. Master progressive data updates, streaming APIs, and real-time user experience patterns.
Key Concepts: Streaming data, progressive updates, chat UX, async iterators
Based on:
examples/react/react-native
Adapt TanStack Query for mobile applications with platform-specific optimizations. Handle app state changes, network connectivity variations, and mobile-specific user interactions.
Key Concepts: Mobile optimization, app state management, network awareness, platform-specific patterns
Based on:
examples/react/optimistic-updates-cache
Master sophisticated optimistic updates that manipulate the cache directly. Learn advanced error recovery, rollback mechanisms, and cache coordination for complex user interactions.
Key Concepts: Cache manipulation, error recovery, rollback strategies, advanced optimistic patterns
Based on:
examples/react/prefetching
Eliminate perceived latency through intelligent data prefetching. Learn predictive loading strategies, user behavior analysis, and performance optimization techniques.
Key Concepts: Predictive loading, performance optimization, user behavior analysis, prefetch strategies
Based on:
examples/react/infinite-query-with-max-pages
Implement memory-efficient infinite scroll with sliding window constraints. Balance infinite UX with finite resources through smart page management and performance boundaries.
Key Concepts: Memory management, sliding windows, performance constraints, bounded infinite scroll
Based on:
examples/react/react-router
Master seamless navigation with router-integrated data fetching. Learn how to coordinate React Router loaders with TanStack Query for instant navigation and predictable data loading patterns.
Key Concepts: Router integration, navigation patterns, loader coordination, search state management
Based on:
examples/react/nextjs-suspense-streaming
Implement progressive server-side rendering with Suspense streaming. Enable fast initial page loads while slower content streams in progressively for optimal user experience.
Key Concepts: Progressive SSR, streaming responses, edge runtime, suspense coordination
Based on:
examples/react/shadow-dom
Build fully isolated embeddable components using Shadow DOM integration. Create widgets and micro-frontends that work reliably in any environment without style or state conflicts.
Key Concepts: Component isolation, embeddable widgets, shadow DOM, cross-boundary communication
For developers who want to get productive quickly:
- Getting Started: Your First Query
- Understanding the Cache
- Optimistic Updates
For developers building production applications:
- All Beginner Track tutorials
- Infinite Scroll with Intersection Observer
- Default Query Function
- Offline-First Applications
- Real-Time Data with Auto-Refetching
- GraphQL Integration
Choose your framework and dive deep:
- Vue Developers: Start with tutorial 6, then follow Comprehensive Path
- Angular Developers: Focus on tutorials 1-2, 4, 7-8 (core patterns translate directly)
- React Developers: Follow Comprehensive Path in order
For experienced developers wanting to master complex scenarios:
- Optimistic Updates
- Infinite Scroll
- Default Query Function
- Offline-First Applications
For developers using cutting-edge React features:
- React Suspense: Concurrent UI Patterns
- Next.js App Router: Server-Side Prefetching
- Real-Time Data with Auto-Refetching
- GraphQL Integration
While these tutorials focus on React and Vue, the core concepts apply to all frameworks:
- Angular:
examples/angular/*- Dependency injection patterns, RxJS integration - Solid:
examples/solid/*- Fine-grained reactivity, SSR patterns - Svelte:
examples/svelte/*- Store integration, SvelteKit patterns
Explore these examples for specialized use cases:
- Real-time Chat:
examples/react/chat- Streaming data patterns - Search with Debouncing:
examples/react/algolia- Advanced search UX - React Native:
examples/react/react-native- Mobile-specific patterns - Cache-Level Optimistic Updates:
examples/react/optimistic-updates-cache - Development Workflow:
examples/*/devtools-panel- Debugging and development
After completing these tutorials:
- Explore Framework-Specific Examples: Try examples in your preferred framework
- Build a Project: Apply these patterns to a real application
- Read the Docs: Dive deeper into official documentation
- Join the Community: Engage with other developers learning Query
Found an issue or want to suggest improvements? These tutorials are living documents that evolve with the community. Check the main repository for contribution guidelines.
Remember: The goal isn't just to learn Query's API, but to understand the mental models and design principles that make it powerful. Focus on the 'why' behind each pattern, and you'll be able to apply these concepts to solve complex data management challenges in any application.