React Fetch Cache Patterns

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

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/:

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

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)