gs-tanstack-react-query_skill

Overview

This skill provides opinionated TanStack React Query integrations following Clean Architecture patterns. It wires server actions to React Query hooks so queries return DTOs and mutations call server actions, with built-in patterns for cache keys, invalidation, optimistic updates, and pagination. Use it to keep data fetching type-safe and aligned with domain boundaries.

How this skill works

Components use hooks like useServerActionQuery, useServerActionMutation, and useServerActionInfiniteQuery that call server actions. Query responses are transformed into DTO types; components never depend on domain entities or direct use case calls. The skill relies on hierarchical query keys and a QueryClient to handle invalidation, optimistic updates, and pagination.

When to use it

• When you fetch data from server actions and want responses typed as DTOs
• When using useQuery/useMutation patterns with TanStack React Query
• When you need structured cache invalidation across lists and details
• When implementing optimistic UI updates with rollback support
• When adding cursor-based pagination with infinite queries

Best practices

• Always type hooks with DTO types (e.g., CategoryDTO) instead of domain entities
• Call only server actions from components—never invoke use cases directly
• Design hierarchical query keys for broad invalidation and specific refetches
• Implement optimistic updates with onMutate/onError/onSettled and store previous state for rollback
• Invalidate parent keys (e.g., ['categories']) after mutations to keep lists fresh

Example use cases

• List active categories with useServerActionQuery returning CategoryDTO[]
• Fetch a single category detail with a key like ['categories','detail',id]
• Create a category with useServerActionMutation and invalidate ['categories'] on success
• Update a category optimistically: patch the detail cache, rollback on error, then invalidate
• Implement infinite scrolling for categories with useServerActionInfiniteQuery and nextCursor