initial commit

.agents/skills/tanstack-query-best-practices/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: tanstack-query-best-practices
+description: TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.
+---
+
+# TanStack Query Best Practices
+
+Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
+
+## When to Apply
+
+- Creating new data fetching logic
+- Setting up query configurations
+- Implementing mutations and optimistic updates
+- Configuring caching strategies
+- Integrating with SSR/SSG
+- Refactoring existing data fetching code
+
+## Rule Categories by Priority
+
+| Priority | Category | Rules | Impact |
+|----------|----------|-------|--------|
+| CRITICAL | Query Keys | 5 rules | Prevents cache bugs and data inconsistencies |
+| CRITICAL | Caching | 5 rules | Optimizes performance and data freshness |
+| HIGH | Mutations | 6 rules | Ensures data integrity and UI consistency |
+| HIGH | Error Handling | 3 rules | Prevents poor user experiences |
+| MEDIUM | Prefetching | 4 rules | Improves perceived performance |
+| MEDIUM | Parallel Queries | 2 rules | Enables dynamic parallel fetching |
+| MEDIUM | Infinite Queries | 3 rules | Prevents pagination bugs |
+| MEDIUM | SSR Integration | 4 rules | Enables proper hydration |
+| LOW | Performance | 4 rules | Reduces unnecessary re-renders |
+| LOW | Offline Support | 2 rules | Enables offline-first patterns |
+
+## Quick Reference
+
+### Query Keys (Prefix: `qk-`)
+
+- `qk-array-structure` — Always use arrays for query keys
+- `qk-include-dependencies` — Include all variables the query depends on
+- `qk-hierarchical-organization` — Organize keys hierarchically (entity → id → filters)
+- `qk-factory-pattern` — Use query key factories for complex applications
+- `qk-serializable` — Ensure all key parts are JSON-serializable
+
+### Caching (Prefix: `cache-`)
+
+- `cache-stale-time` — Set appropriate staleTime based on data volatility
+- `cache-gc-time` — Configure gcTime for inactive query retention
+- `cache-defaults` — Set sensible defaults at QueryClient level
+- `cache-invalidation` — Use targeted invalidation over broad patterns
+- `cache-placeholder-vs-initial` — Understand placeholder vs initial data differences
+
+### Mutations (Prefix: `mut-`)
+
+- `mut-invalidate-queries` — Always invalidate related queries after mutations
+- `mut-optimistic-updates` — Implement optimistic updates for responsive UI
+- `mut-rollback-context` — Provide rollback context from onMutate
+- `mut-error-handling` — Handle mutation errors gracefully
+- `mut-loading-states` — Use isPending for mutation loading states
+- `mut-mutation-state` — Use useMutationState for cross-component tracking
+
+### Error Handling (Prefix: `err-`)
+
+- `err-error-boundaries` — Use error boundaries with useQueryErrorResetBoundary
+- `err-retry-config` — Configure retry logic appropriately
+- `err-fallback-data` — Provide fallback data when appropriate
+
+### Prefetching (Prefix: `pf-`)
+
+- `pf-intent-prefetch` — Prefetch on user intent (hover, focus)
+- `pf-route-prefetch` — Prefetch data during route transitions
+- `pf-stale-time-config` — Set staleTime when prefetching
+- `pf-ensure-query-data` — Use ensureQueryData for conditional prefetching
+
+### Infinite Queries (Prefix: `inf-`)
+
+- `inf-page-params` — Always provide getNextPageParam
+- `inf-loading-guards` — Check isFetchingNextPage before fetching more
+- `inf-max-pages` — Consider maxPages for large datasets
+
+### SSR Integration (Prefix: `ssr-`)
+
+- `ssr-dehydration` — Use dehydrate/hydrate pattern for SSR
+- `ssr-client-per-request` — Create QueryClient per request
+- `ssr-stale-time-server` — Set higher staleTime on server
+- `ssr-hydration-boundary` — Wrap with HydrationBoundary
+
+### Parallel Queries (Prefix: `parallel-`)
+
+- `parallel-use-queries` — Use useQueries for dynamic parallel queries
+- `query-cancellation` — Implement query cancellation properly
+
+### Performance (Prefix: `perf-`)
+
+- `perf-select-transform` — Use select to transform/filter data
+- `perf-structural-sharing` — Leverage structural sharing
+- `perf-notify-change-props` — Limit re-renders with notifyOnChangeProps
+- `perf-placeholder-data` — Use placeholderData for instant UI
+
+### Offline Support (Prefix: `offline-`)
+
+- `network-mode` — Configure network mode for offline support
+- `persist-queries` — Configure query persistence for offline support
+
+## How to Use
+
+Each rule file in the `rules/` directory contains:
+1. **Explanation** — Why this pattern matters
+2. **Bad Example** — Anti-pattern to avoid
+3. **Good Example** — Recommended implementation
+4. **Context** — When to apply or skip this rule
+
+## Full Reference
+
+See individual rule files in `rules/` directory for detailed guidance and code examples.