madappgang/claude-code

Overview

This skill provides practical patterns and TypeScript-safe utilities for managing server state with TanStack Query v5 in React 18+ apps. It focuses on query key factories, queryOptions, data transformation, optimistic mutations, Suspense integration, authentication handling, and testing guidance. The goal is predictable, maintainable async state with production-ready defaults and feature-based colocation.

How this skill works

It defines hierarchical query key factories and private query functions, then exposes only custom hooks and queryOptions for full type safety. Hooks use the single-object v5 API (queryKey + queryFn inside one config) and leverage select for efficient data transformation. Mutation patterns include optimistic updates with rollback using onMutate/onError/onSettled and QueryClient methods. Global error handling is set via QueryCache callbacks and Suspense hooks are available for type-safe loading states.

When to use it

• When you need robust caching, background refetching, and deduplication for server data.
• When you want full TypeScript inference across hooks and imperative QueryClient calls.
• When implementing optimistic UI for create/update/delete flows with safe rollback.
• When adopting Suspense to simplify loading states and guarantee defined data types.
• When colocating feature logic (keys, functions, hooks) for maintainability and testability.

Best practices

• Use hierarchical query key factories that include every variable used by queryFn.
• Export only custom hooks and queryOptions; keep queryFns and keys private to the feature.
• Prefer select for UI-specific transforms and memoize select functions to avoid re-runs.
• Use queryOptions helper for one source of truth and full TypeScript inference in imperative calls.
• In optimistic updates, cancel queries, snapshot previous data, set new data immutably, and rollback on error.

Example use cases

• Create a feature folder with queries.ts exporting useTodosQuery and todoOptions for typed prefetching and cache access.
• Implement optimistic update for editing a todo: onMutate snapshot -> setQueryData -> rollback in onError -> invalidate onSettled.
• Switch a list view to use useSuspenseQuery wrapped by a Suspense boundary to remove manual loading states.
• Use QueryCache onError to show background error toasts only when cached data exists.
• Write tests with MSW by calling queryClient.prefetchQuery(todoOptions(id)) to seed cache before rendering components.