Agent Skills: Experimental React Data Fetching & Caching Best Practices

Experimental React Data Fetching & Caching Best Practices

Implementation patterns for React applications that fetch and cache many API requests without overwhelming the backend. 48 rules across 8 categories, ordered by execution lifecycle impact — earlier categories cascade through everything downstream. Templates show both library-based (TanStack Query, SWR) and library-free (pure React + AbortController) implementations so the patterns are usable regardless of stack constraints.

When to Apply

• Writing or reviewing a React component that calls fetch, useQuery, useSWR, or any data-fetching hook
• Designing a list, feed, or carousel that displays many items each requiring data
• Investigating "the backend is getting hammered" or "the page loads slowly" symptoms
• Choosing between client-side fetching, route loaders, server components, or SSR
• Implementing prefetch, retry, optimistic updates, or any failure-handling logic
• Refactoring code that already does data fetching but with waterfalls, no cache strategy, or no concurrency limits

Rule Categories by Priority

| # | Category | Impact | Prefix | Rules | |---|----------|--------|--------|-------| | 1 | Request Orchestration | CRITICAL | orch- | 7 | | 2 | Cache Strategy | CRITICAL | cache- | 7 | | 3 | Backend Protection | CRITICAL | protect- | 7 | | 4 | Prefetch & Hydration | HIGH | prefetch- | 6 | | 5 | Failure Resilience | HIGH | resilience- | 6 | | 6 | Feed & Carousel Patterns | MEDIUM-HIGH | feed- | 7 | | 7 | Mutation & Invalidation | MEDIUM | mutate- | 4 | | 8 | Component Patterns | MEDIUM | render- | 4 |

Quick Reference

1. Request Orchestration (CRITICAL)

• orch-parallelize-independent-fetches — Use Promise.all for independent requests; never serial await
• orch-batch-n-plus-one-fanout — Collapse per-row fetches via DataLoader-style batching
• orch-dedupe-in-flight-requests — One in-flight request per key, shared across subscribers
• orch-lift-fetch-to-route-loader — Fetch in parallel with route chunk download
• orch-avoid-effect-chains — Flatten the dependency graph; only true dependencies wait
• orch-server-fetch-when-possible — Move fetches to RSC/server when they don't depend on client state
• orch-prefer-bulk-endpoint-for-fanout — One bulk request beats N parallel requests

2. Cache Strategy (CRITICAL)

• cache-deterministic-keys — Canonicalize cache keys; strip undefined, sort arrays
• cache-normalize-shared-entities — Store each entity once; views hold references
• cache-set-stale-time — Tune staleTime to data volatility, not refresh frequency
• cache-stale-while-revalidate — Render stale instantly; revalidate in background
• cache-select-subscribed-fields — Subscribe to slices, not whole objects
• cache-shared-key-factory — One typed source of truth for keys; prevents read/write drift
• cache-tiered-stale-fresh — Different staleTime per data class (realtime, fresh, warm, cold, static)

3. Backend Protection (CRITICAL)

• protect-concurrency-limit-fanout — Cap simultaneous requests with p-limit/semaphore
• protect-collapse-identical-requests — In-flight dedup at the fetch layer
• protect-debounce-user-driven-fetches — Wait for user pause before firing search/filter requests
• protect-throttle-scroll-triggered — Use IntersectionObserver for viewport-triggered fetches
• protect-jittered-retry-backoff — Add random jitter to prevent thundering-herd retries
• protect-circuit-breaker — Stop calling persistently failing endpoints for a cooldown window
• protect-rate-limit-aware-client — Honor Retry-After and X-RateLimit-* headers

4. Prefetch & Hydration (HIGH)

• prefetch-hover-intent-links — Prefetch on hover/pointerdown for instant navigation
• prefetch-parallel-loader-queries — Parallelize independent queries inside loaders
• prefetch-hydrate-server-cache — Ship server-fetched data via HydrationBoundary / RSC
• prefetch-idle-likely-next — Use requestIdleCallback for likely-next data
• prefetch-viewport-triggered-next-page — Fire next-page prefetch via rootMargin
• prefetch-budget-and-priority — Tier prefetches by priority; respect Save-Data

5. Failure Resilience (HIGH)

• resilience-abort-on-unmount — Forward AbortSignal to cancel stale fetches
• resilience-bounded-timeouts — Set per-endpoint timeouts via AbortSignal.timeout()
• resilience-scoped-error-boundaries — One boundary per data section, not per page
• resilience-stale-fallback — Render stale cache when fresh fetch fails
• resilience-no-auto-retry-mutations — Use idempotency keys or don't auto-retry
• resilience-graceful-degradation — Critical/important/decorative tiers with different failure modes

6. Feed & Carousel Patterns (MEDIUM-HIGH)

• feed-virtualize-long-lists — Use TanStack Virtual for lists > 50 items
• feed-cursor-pagination — Cursors beat offset for inserts and large offsets
• feed-split-summary-from-detail — Carousel summaries lightweight; detail on demand
• feed-multi-carousel-isolation — Per-carousel error/Suspense boundaries + tiered fallbacks for homepage feeds
• feed-stable-keys-across-pages — Use entity IDs as keys; never index
• feed-image-lazy-and-sized — loading="lazy" + explicit dimensions
• feed-bounded-working-set — maxPages + entity LRU eviction for unbounded feeds

7. Mutation & Invalidation (MEDIUM)

• mutate-optimistic-updates-with-rollback — Snapshot, optimistic write, rollback on error
• mutate-surgical-invalidation — Invalidate specific keys, not entire trees
• mutate-set-data-over-invalidate — Write mutation responses directly into the cache
• mutate-cancel-queries-on-mutate — Cancel in-flight queries before optimistic writes

8. Component Patterns (MEDIUM)

• render-stable-query-keys — useMemo object keys to keep references stable
• render-cap-fanout-in-lists — Lift fetches; batch via DataLoader; virtualize
• render-suspense-per-section — One Suspense boundary per data section
• render-colocate-fetch-with-consumer — Put useQuery next to its consumer, not at the root

How to Use

1. Open references/_sections.md for category definitions and impact rationale
2. Read individual rule files for incorrect-vs-correct code examples
3. For ready-to-use scaffolds, see scaffolding templates
4. The AGENTS.md navigation document (auto-generated) provides a TOC for browsing

Scaffolding Templates

Six ready-to-adapt code templates under assets/templates/:

| Template | Library deps | Purpose | |----------|-------------|---------| | use-resource-query.template.tsx | TanStack Query | Standard query hook with key factory, retry, abort, optional suspense | | use-resource-query-no-deps.template.tsx | None (pure React + AbortController) | Same patterns as above, library-free: hand-rolled cache, dedup, retry with jitter, staleTime/gcTime, concurrency limit | | carousel-data-loader.template.tsx | TanStack Query + react-error-boundary | Single carousel (summary + viewport-triggered detail) and multi-carousel feed with per-carousel failure isolation | | infinite-feed.template.tsx | TanStack Query + TanStack Virtual | Cursor-paginated infinite feed with virtualization and bounded working set | | prefetch-link.template.tsx | None | Hover/intent prefetch link wrapper | | request-collapser.template.ts | None | In-flight deduplication + concurrency limit utility |

Library-free path: if you can't add TanStack Query / SWR / DataLoader to your bundle (size constraints, host-app conflicts, dependency bans), start with use-resource-query-no-deps.template.tsx — it implements the core cache/dedup/retry/abort patterns in ~250 lines using only React and the web platform. The other templates that depend on TanStack can be adapted on top of it; only the request-collapser and prefetch-link templates are zero-dep out of the box.

Reference Files

| File | Description | |------|-------------| | references/_sections.md | Category definitions, ordering, impact rationale | | assets/templates/_template.md | Template for authoring new rules | | metadata.json | Version, references, abstract |

Related Skills

• react-optimise — General React render performance (this skill is data-fetching-specific)
• nextjs-bundle-optimizer — Bundle/payload optimization for Next.js
• inngest-nextjs-patterns — Server-side workflow patterns (complements server-fetch guidance)