React Query POC - Comprehensive Implementation

This is a production-quality Proof of Concept (POC) demonstrating React Query (TanStack Query) best practices and core concepts through a Library Management System.

📚 Concepts Demonstrated

Query Fundamentals

• ✅ Basic query setup with useQuery
• ✅ Query keys and dependency management
• ✅ Query lifecycle (fresh, fetching, stale, inactive)
• ✅ Automatic background refetching
• ✅ Cache deduplication
• ✅ Query invalidation

Data Fetching Patterns

• ✅ On-Demand Fetching: Manual query triggering
• ✅ Polling: Automatic refetch intervals
• ✅ Dependent Queries: Queries that depend on previous query results
• ✅ Parallel Queries: Multiple queries running simultaneously
• ✅ Pagination: Cursor and page-based pagination
• ✅ Infinite Queries: Infinite scroll implementation

Cache Management

• ✅ Deduplication: Prevents duplicate requests
• ✅ Garbage Collection: Automatic cleanup of unused cache
• ✅ Cache Time: Control cache retention
• ✅ Stale Time: Control when data is considered stale
• ✅ Window Focus Refetching: Re-fetch on window focus
• ✅ Optimistic Updates: Update UI before server confirmation

Mutations

• ✅ Basic mutations with useMutation
• ✅ Mutation success/error handling
• ✅ Optimistic updates
• ✅ Cache invalidation after mutations
• ✅ Rollback on error

Advanced Features

• ✅ Error boundaries and error handling
• ✅ Loading states and suspense
• ✅ Prefetching
• ✅ Query retries with exponential backoff
• ✅ Request cancellation
• ✅ TypeScript integration

🏗️ Architecture

src/
├── api/
│   ├── client.ts          # API client configuration
│   ├── books.api.ts       # Books API endpoints
│   ├── reviews.api.ts     # Reviews API endpoints
│   └── users.api.ts       # Users API endpoints
├── hooks/
│   ├── queries/
│   │   ├── useBooks.ts    # Book-related queries
│   │   ├── useReviews.ts  # Review queries
│   │   └── useUsers.ts    # User queries
│   └── mutations/
│       ├── useBookMutations.ts    # Book mutations
│       └── useReviewMutations.ts  # Review mutations
├── types/
│   ├── book.types.ts      # Book-related types
│   ├── review.types.ts    # Review types
│   └── api.types.ts       # API response types
├── components/
│   ├── books/             # Book-related components
│   ├── reviews/           # Review components
│   ├── common/            # Shared components
│   └── layout/            # Layout components
├── pages/
│   ├── Books.tsx          # Books listing page
│   ├── BookDetail.tsx     # Book detail page
│   ├── Reviews.tsx        # Reviews page
│   └── Dashboard.tsx      # Dashboard with stats
├── utils/
│   ├── queryClient.ts     # Query client configuration
│   └── helpers.ts         # Utility functions
├── App.tsx                # Main app component
└── main.tsx              # Entry point

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

📖 Key Features

1. Book Management

• View all books with pagination
• Search and filter books
• View book details with reviews
• Check book availability
• Checkout/return books

2. Review System

• View reviews for books
• Add new reviews
• Edit/delete reviews (optimistic updates)
• Real-time review updates

3. Activity Feed

• Latest activity across the library
• Polling for new activities
• Activity filters

4. Search

• Instant search with debouncing
• Search across books, authors, and genres

🎯 React Query Patterns Demonstrated

Query Keys Pattern

// Hierarchical query keys for easy invalidation
['books'] // All books
['books', { page: 1 }] // Books page 1
['books', bookId] // Specific book
['books', bookId, 'reviews'] // Book reviews

Dependent Queries

// Only fetch reviews after book data is loaded
const { data: book } = useBook(bookId);
const { data: reviews } = useBookReviews(bookId, {
  enabled: !!book,
});

Optimistic Updates

// Update UI immediately, rollback on error
mutate(newData, {
  onMutate: async (newData) => {
    // Cancel outgoing refetches
    await queryClient.cancelQueries({ queryKey: ['books'] });
    
    // Snapshot previous value
    const previous = queryClient.getQueryData(['books']);
    
    // Optimistically update
    queryClient.setQueryData(['books'], (old) => [...old, newData]);
    
    return { previous };
  },
  onError: (err, newData, context) => {
    // Rollback on error
    queryClient.setQueryData(['books'], context.previous);
  },
});

Infinite Scroll

const {
  data,
  fetchNextPage,
  hasNextPage,
  isFetchingNextPage,
} = useInfiniteQuery({
  queryKey: ['books', 'infinite'],
  queryFn: ({ pageParam = 0 }) => fetchBooks(pageParam),
  getNextPageParam: (lastPage) => lastPage.nextCursor,
});

🔧 Configuration

Query Client Setup

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      gcTime: 1000 * 60 * 30, // 30 minutes (formerly cacheTime)
      refetchOnWindowFocus: true,
      refetchOnReconnect: true,
      retry: 3,
      retryDelay: (attemptIndex) => 
        Math.min(1000 * 2 ** attemptIndex, 30000),
    },
  },
});

📝 Mock API

The POC includes a complete mock API that simulates:

• Network delays
• Error scenarios
• Pagination
• Search functionality
• CRUD operations

🎨 UI Notes

The UI is intentionally simple and functional to keep focus on React Query implementation patterns. The emphasis is on:

• Clean, maintainable code
• Proper error handling
• Loading state management
• TypeScript type safety
• Production-ready patterns

📚 Learning Resources

Each component includes detailed comments explaining:

• Why specific React Query options are used
• How the query/mutation works
• Best practices being followed
• Common pitfalls to avoid

🤝 Contributing

This POC is designed as a reference implementation. Feel free to:

• Extend with additional features
• Add more complex query patterns
• Improve UI/UX
• Add tests

📄 License

MIT

🙏 Acknowledgments

Based on "The Official React Query Course" by ui.dev