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)

React Data Fetching & Caching

Version 0.1.0 Experimental May 2026

Note:

This document is mainly for agents and LLMs to follow when maintaining,

generating, or refactoring codebases. Humans may also find it useful,

but guidance here is optimized for automation and consistency by AI-assisted workflows.

---

Abstract

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: Request Orchestration (parallelism, batching, deduplication, route loaders), Cache Strategy (deterministic keys, normalization, staleTime, stale-while-revalidate, key factories, tiered freshness), Backend Protection (concurrency caps, request collapsing, debounce/throttle, jittered retries, circuit breakers, rate-limit awareness), Prefetch & Hydration (hover/intent prefetch, parallel loader queries, server hydration, idle prefetch, viewport-triggered, budget tiers), Failure Resilience (AbortController, bounded timeouts, scoped error boundaries, stale fallback, mutation idempotency, graceful degradation), Feed & Carousel Patterns (virtualization, cursor pagination, summary/detail split, multi-carousel failure isolation, stable keys, lazy images, bounded working set), Mutation & Invalidation (optimistic updates with rollback, surgical invalidation, setQueryData, cancel-on-mutate), and Component Patterns (stable query keys, fan-out caps, Suspense per section, colocation). Bundled with 6 scaffolding templates including both library-based (TanStack Query) and library-free (pure React + AbortController) implementations: resource query hook, no-deps resource query hook, carousel data loader (single + multi-carousel feed with failure isolation), infinite feed, prefetch link, request collapser.

---

Table of Contents

1. Request Orchestration — CRITICAL

• 1.1 Avoid useEffect Fetch Chains — CRITICAL (prevents render-fetch-render-fetch waterfalls)
• 1.2 Batch N+1 Fan-Out with DataLoader Pattern — CRITICAL (reduces N requests to 1)
• 1.3 Deduplicate In-Flight Requests by Key — CRITICAL (reduces M concurrent calls to 1)
• 1.4 Lift Fetches into Route Loaders — CRITICAL (200-800ms saved on route entry)
• 1.5 Move Fetches to the Server When Possible — HIGH (eliminates client-side round-trip + JS payload)
• 1.6 Parallelize Independent Fetches — CRITICAL (eliminates N-1 sequential round-trips)
• 1.7 Prefer a Bulk Endpoint over N Parallel Endpoints — CRITICAL (reduces N round-trips to 1)

2. Cache Strategy — CRITICAL

• 2.1 Build Deterministic Cache Keys — CRITICAL (prevents accidental cache misses on every render)
• 2.2 Centralize Cache Keys in a Key Factory — CRITICAL (prevents read/write key drift)
• 2.3 Normalize Shared Entities Across Views — CRITICAL (N-fold cache size reduction for shared entities)
• 2.4 Set staleTime to Suppress Redundant Refetches — CRITICAL (5-50x reduction in refetch rate)
• 2.5 Tier staleTime by Data Volatility — HIGH (reduces stale-data refetches 10-100×)
• 2.6 Use select to Subscribe to a Subset of Cache Data — CRITICAL (5-20x reduction in re-render rate)
• 2.7 Use Stale-While-Revalidate for Instant Renders — CRITICAL (0ms perceived wait for cached data)

3. Backend Protection — CRITICAL

• 3.1 Add Jitter to Retry Backoff — CRITICAL (prevents thundering-herd recovery)
• 3.2 Cap Concurrency on Client-Side Fan-Out — CRITICAL (prevents browser connection exhaustion + backend overload)
• 3.3 Collapse Identical Requests at the Fetch Layer — HIGH (prevents auth-refresh storms and retry-original races)
• 3.4 Debounce User-Driven Fetches — HIGH (10-30× reduction in search/filter requests)
• 3.5 Honor Server Rate-Limit Headers Client-Side — HIGH (prevents 429 retry loops + ban risk)
• 3.6 Throttle Scroll-Triggered Fetches — HIGH (reduces 60Hz event firing to 4-10Hz fetches)
• 3.7 Use Circuit Breakers on Persistently Failing Endpoints — HIGH (prevents retry storms on persistent failure)

4. Prefetch & Hydration — HIGH

• 4.1 Bound Prefetch Bandwidth by Priority Tier — MEDIUM-HIGH (prevents prefetch from competing with critical fetches)
• 4.2 Hydrate the Client Cache from Server-Rendered Data — HIGH (eliminates first-fetch on cached entities)
• 4.3 Prefetch Likely-Next Data on Idle — MEDIUM-HIGH (maintains instant transitions for predictable paths)
• 4.4 Prefetch Links on Hover and Intent — HIGH (100-300ms faster perceived navigation)
• 4.5 Prefetch the Next Page Before the Sentinel Hits Viewport — HIGH (eliminates loading-more spinners in feeds)
• 4.6 Run Route Loader Queries in Parallel — HIGH (reduces N sequential awaits to 1 round-trip)

5. Failure Resilience — HIGH

• 5.1 Abort Requests on Unmount or Navigation — HIGH (prevents stale-response races and memory leaks)
• 5.2 Avoid Auto-Retrying Non-Idempotent Mutations — HIGH (prevents double-charging, duplicate posts, double sends)
• 5.3 Bound Request Timeouts per Endpoint Class — HIGH (prevents indefinite hangs on degraded backends)
• 5.4 Fall Back to Stale Cache When Fresh Fetch Fails — HIGH (prevents temporary outages from becoming visible errors)
• 5.5 Gracefully Degrade Non-Critical Sections — MEDIUM-HIGH (preserves core flow when peripheral data fails)
• 5.6 Scope Error Boundaries to Data Sections — HIGH (prevents one fetch failure from breaking the entire page)

6. Feed & Carousel Patterns — MEDIUM-HIGH

• 6.1 Bound the In-Memory Working Set on Long Feeds — MEDIUM-HIGH (prevents unbounded memory growth on infinite scroll)
• 6.2 Defer Off-Screen Feed Images with Explicit Dimensions — MEDIUM-HIGH (prevents layout shift and saves 70-90% image bandwidth)
• 6.3 Isolate Failure Across a Feed of Carousels — MEDIUM-HIGH (prevents one failing carousel from breaking the homepage)
• 6.4 Split Carousel Summaries from Item Details — MEDIUM-HIGH (reduces initial carousel payload 5-20×)
• 6.5 Use Cursor Pagination over Offset — MEDIUM-HIGH (prevents skip/duplicate items as the list shifts)
• 6.6 Use Stable Item Keys Across Paginated Pages — MEDIUM (prevents full-list re-render on each new page)
• 6.7 Virtualize Long Lists Beyond ~50 Items — MEDIUM-HIGH (10-100× fewer DOM nodes)

7. Mutation & Invalidation — MEDIUM

• 7.1 Apply Optimistic Updates with Rollback on Failure — MEDIUM (eliminates 200-800ms perceived mutation latency)
• 7.2 Cancel In-Flight Queries Before Mutating Their Cache — MEDIUM (prevents race conditions between mutation and refetch)
• 7.3 Invalidate Surgically, Not Globally — MEDIUM (reduces post-mutation refetch storms 10-100×)
• 7.4 Use setQueryData over Invalidate When the Result is Known — MEDIUM (eliminates 1 refetch per mutation)

8. Component Patterns — MEDIUM

• 8.1 Cap Fan-Out of Queries Inside Lists — MEDIUM (prevents unbounded query fan-out as lists grow)
• 8.2 Colocate Fetches with Their Consumers — MEDIUM (prevents prop drilling and unnecessary re-renders up the tree)
• 8.3 Place Suspense Boundaries Per Logical Section — MEDIUM (enables independent streaming of data sections)
• 8.4 Stabilize Object-Shaped Query Keys — MEDIUM (prevents new fetch on every parent render)

---

References

1. https://react.dev/reference/react/Suspense 2. https://tanstack.com/query/latest/docs/framework/react/overview 3. https://swr.vercel.app/ 4. https://nextjs.org/docs/app/building-your-application/data-fetching 5. https://tanstack.com/router/latest/docs/framework/react/guide/data-loading 6. https://tanstack.com/virtual/latest 7. https://vercel.com/blog/everything-about-data-fetching-in-nextjs 8. https://github.com/graphql/dataloader 9. https://developer.mozilla.org/en-US/docs/Web/API/AbortController 10. https://datatracker.ietf.org/doc/html/rfc5861 11. https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ 12. https://tkdodo.eu/blog/practical-react-query

---

Source Files

This document was compiled from individual reference files. For detailed editing or extension:

{Title}

{1-3 sentences explaining WHY this matters. What goes wrong without this pattern, and what the cascade effect is. This section is the highest-signal part of the rule — the model generalizes from understood reasoning, not from rules. Don't just say "use X" — explain the failure mode in concrete terms the model can internalize.

For data-fetching rules, frame the failure in terms of: extra round-trips, extra backend load, extra bytes downloaded, layout shift, race conditions, retry storms, or memory leaks. The mechanism is what makes the rule generalize to novel scenarios.}

Incorrect ({problem label}):

{Production-realistic bad code — not a strawman.}
{Examples should use real names (CommentList, ProductCarousel) not foo/bar.}
{Comments explain the *cost*: "// 200 requests" or "// blocks main thread".}
function BadExample() {
  const { data } = useFetch('/api/things'); // 🚨 explanation of what's wrong
}

Correct ({solution label}):

{Good code — minimal diff from incorrect when possible.}
{Comments explain the *benefit*.}
function GoodExample() {
  const { data } = useQuery({
    queryKey: ['things'],
    queryFn: fetchThings,
    staleTime: 30_000,                       // ← the fix
  });
}

{Optional sections — include only when they add value:}

Alternative ({context}):

{Alternative valid approach}

Implementation ({name of pattern}):

{Reusable utility worth shipping with the rule}

With {framework/tool}:

{Tool-specific variant — e.g., Next.js App Router, TanStack Router, SWR}

When NOT to use this pattern:

• {Specific exception with rationale}
• {Another specific exception}

Warning ({context}):

• {Gotcha that would burn a careful reader}

Benefits:

• {Concrete benefit 1}
• {Concrete benefit 2}

Pair with [[other-rule-slug]]: {how this rule combines with another}

Reference: [{Source Title}]({source URL — use authoritative sources only})

Sections

This file defines all sections, their ordering, impact levels, and descriptions. The section ID (in parentheses) is the filename prefix used to group rules.

Categories are ordered by lifecycle position and cascade effect. Problems at the top (orchestration, cache keys) multiply downstream — getting them wrong creates hundreds of redundant backend hits per user. Problems at the bottom (render patterns, mutation invalidation) are localized and addable later.

Impact tier definitions

Used by rule frontmatter and category headings:

A rule's tier is independent of its category's tier — a CRITICAL category can contain HIGH or MEDIUM rules, and vice versa. The category tier reflects the typical severity of issues in that domain; individual rule tiers reflect the specific impact of each pattern.

---

1. Request Orchestration (orch)

Impact: CRITICAL Description: How concurrent fetches are coordinated — parallelism vs waterfalls, batching of N+1 fan-out, in-flight deduplication, and lifting fetches into route loaders. Wrong orchestration multiplies latency (sequential awaits) and multiplies backend load (every child component independently fetching). The single biggest source of backend overload from React apps.

2. Cache Strategy (cache)

Impact: CRITICAL Description: How fetched data is keyed, stored, and shared across components — deterministic cache keys, normalized graph cache for shared entities (the same product appearing in three carousels), stale-while-revalidate semantics, staleTime, and selector-scoped subscriptions. A bad key strategy creates a cache miss for every user; a flat cache forces N requests for the same entity reused N times.

3. Backend Protection (protect)

Impact: CRITICAL Description: Guardrails that prevent the client from overwhelming the backend — concurrency caps on fan-out, request collapsing for identical in-flight calls, debounce/throttle on user-driven triggers, and stampede protection (jittered retries, cache-warming locks). Without these, a refresh, a viral page, or a brief backend slowdown becomes a self-DDoS.

4. Prefetch & Hydration (prefetch)

Impact: HIGH Description: Eager fetching strategies that start requests before the component needs them — route loaders, hover/intent prefetch, idle-time and viewport-triggered prefetch, and server-rendered cache hydration. Done right, this shifts latency out of the user's critical path; done wrong, it doubles backend load by prefetching data the user never views.

5. Failure Resilience (resilience)

Impact: HIGH Description: Patterns that keep the app working when fetches fail — exponential backoff with jitter, circuit breakers, request cancellation via AbortController, scoped error boundaries, and stale-cache fallback. Naive retries turn transient blips into outages by hammering the recovering service; missing cancellation leaks completed requests after navigation.

6. Feed & Carousel Patterns (feed)

Impact: MEDIUM-HIGH Description: Patterns specific to feeds and recommender carousels at scale — virtualization, cursor-based pagination, infinite query dedup, splitting summary fetches from detail fetches, and viewport-triggered detail loading. These collapse hundreds of off-screen renders and hundreds of unviewed-item detail fetches into a bounded working set.

7. Mutation & Invalidation (mutate)

Impact: MEDIUM Description: How writes update the cache — optimistic updates with rollback, surgical invalidation (target specific keys, not entire trees), setQueryData instead of refetch when the result is known, and mutation idempotency. Wrong invalidation triggers an avalanche of refetches; over-aggressive invalidation defeats the cache.

8. Component Patterns (render)

Impact: MEDIUM Description: Component-level patterns that prevent render-driven re-fetches — stable query keys, scoped Suspense boundaries, fan-out caps inside map(), selector hooks that subscribe to only the rendered fields, and co-locating queries near the components that consume them. These collapse re-render storms and prevent components from accidentally refetching on every parent update.

Build Deterministic Cache Keys

Cache keys are compared structurally. { id: 1, type: 'A' } and { type: 'A', id: 1 } look equal but their JSON serializations differ — a serialization-based cache would store them as two entries. New object literals on every render produce a new key on every render, so the cache never hits. Canonicalize: sort keys, drop undefined values, strip irrelevant fields.

TanStack Query handles object key ordering automatically but does not strip undefined or sort arrays — if you pass user-controlled filters, normalize them before they become a key.

Incorrect (filter object built inline on every render, undefined fields, unsorted IDs):

function ProductList({ category, minPrice }: Filters) {
  // New object literal each render → new key reference each render
  const filters = { category, minPrice, ids: selectedIds };
  // selectedIds order varies; minPrice may be undefined when not set
  const { data } = useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetchProducts(filters),
  });
  // Result: ['products', {category: 'A', minPrice: undefined, ids: [3,1,2]}] ≠
  //         ['products', {category: 'A', ids: [1,2,3]}] — cache misses
}

Correct (canonicalize: strip undefined, sort arrays, fixed shape):

function canonicalKey<T extends object>(obj: T): T {
  return Object.fromEntries(
    Object.entries(obj)
      .filter(([, v]) => v !== undefined)
      .sort(([a], [b]) => a.localeCompare(b))
      .map(([k, v]) => [k, Array.isArray(v) ? [...v].sort() : v])
  ) as T;
}

function ProductList({ category, minPrice }: Filters) {
  const filters = useMemo(
    () => canonicalKey({ category, minPrice, ids: selectedIds }),
    [category, minPrice, selectedIds]
  );
  const { data } = useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetchProducts(filters),
  });
}

Tag-style alternative (avoid serializing complex filters entirely):

// Hash the filters once, use the hash as the key
const filterHash = useMemo(() => hashFilters(filters), [filters]);
useQuery({ queryKey: ['products', filterHash], queryFn: () => fetchProducts(filters) });

Warning: never include Date.now(), Math.random(), or non-serializable values (functions, class instances) in a cache key — every render produces a fresh key and the cache becomes a memory leak.

Reference: TanStack Query — Query Keys

Normalize Shared Entities Across Views

If a product appears in three carousels and a search result on the same page, a flat (query-keyed) cache stores it four times — and updates to "is in cart" propagate to only the one the user clicked. A normalized cache stores each entity once by ID; views hold references. Update once, all four views re-render with the new state.

This is what Relay, Apollo, RTK Query, and Normy do automatically. TanStack Query is flat by default — for high entity reuse, either layer Normy on top or denormalize-then-update via setQueryData after mutations.

Incorrect (flat cache: same product cached four times):

// Each of these queries stores its own copy of overlapping product objects
useQuery({ queryKey: ['carousel', 'trending'], queryFn: fetchTrendingProducts });
useQuery({ queryKey: ['carousel', 'recently-viewed'], queryFn: fetchRecentProducts });
useQuery({ queryKey: ['carousel', 'recommended'], queryFn: fetchRecommendations });
useQuery({ queryKey: ['search', term], queryFn: () => searchProducts(term) });

// User mutates "add to favorites" on product #42 in trending
queryClient.setQueryData(['carousel', 'trending'], updateFavorite(/*...*/));
// → only the trending carousel re-renders; the same product in 'recently-viewed' stays stale

Correct (normalize: store product once, queries hold IDs):

// Normalized store (Zustand/Jotai/custom) keyed by entity type + id
type Store = {
  products: Map<string, Product>;
  setProducts: (ps: Product[]) => void;
};

// Query stores only the IDs; rendering reads details from the store
const { data: ids } = useQuery({
  queryKey: ['carousel', 'trending'],
  queryFn: async () => {
    const products = await fetchTrendingProducts();
    productStore.setProducts(products); // dump entities into normalized store
    return products.map(p => p.id);       // query stores just the order
  },
});

function ProductCard({ id }: { id: string }) {
  const product = useProductStore(s => s.products.get(id)); // re-renders when THIS product changes
  return <Card product={product!} />;
}

// One mutation, all four views update:
function favoriteProduct(id: string) {
  productStore.setProducts([{ ...productStore.products.get(id)!, isFavorite: true }]);
}

Alternative (Normy as a drop-in layer):

import { createQueryNormalizer } from '@normy/react-query';
// Normy reads response shapes, indexes by `id`, and surgically updates all queries
// that contain entities with that id. Zero per-query code.

When NOT to normalize: when entities are rarely shared between views (e.g. a settings page with unique data per route). The normalization tax isn't worth it.

Reference: Normy — Automatic Normalization

Use select to Subscribe to a Subset of Cache Data

A component subscribed to useQuery({ queryKey: ['user', id] }) re-renders any time any field of the user object changes — even if it only displays user.name. In a feed where each row subscribes to a chunky user object, an unrelated update to user.lastSeenAt re-renders every row. select transforms the cache value and the component re-renders only when the selected slice changes.

Same pattern in Zustand, Redux's useSelector, Jotai's atoms. The principle: subscribe to the minimum slice you render.

Incorrect (subscribe to whole user, re-render on any field change):

function CommentAvatar({ authorId }: { authorId: string }) {
  // Re-renders any time *anything* on the user changes — name, bio, lastSeenAt, isOnline...
  const { data: user } = useQuery({
    queryKey: ['user', authorId],
    queryFn: () => fetchUser(authorId),
  });
  return <Avatar src={user?.avatarUrl} />; // we only need avatarUrl!
}

Correct (select narrows the subscription to the rendered field):

function CommentAvatar({ authorId }: { authorId: string }) {
  const { data: avatarUrl } = useQuery({
    queryKey: ['user', authorId],
    queryFn: () => fetchUser(authorId),
    select: user => user.avatarUrl, // re-render only when avatarUrl changes
  });
  return <Avatar src={avatarUrl} />;
}

Multiple consumers of the same query, each selecting different fields:

function useUserAvatar(id: string) {
  return useQuery({ queryKey: ['user', id], queryFn: () => fetchUser(id), select: u => u.avatarUrl });
}
function useUserName(id: string) {
  return useQuery({ queryKey: ['user', id], queryFn: () => fetchUser(id), select: u => u.name });
}
// One fetch, two narrow subscriptions — name update doesn't re-render avatar consumers.

Implementation note: select must produce a stable reference for the same input. Returning { a, b } on every call creates a new object each time and defeats memoization — return primitives, or wrap the projector in useCallback and produce equal results.

Reference: TanStack Query — Render Optimizations

Set staleTime to Suppress Redundant Refetches

By default, TanStack Query treats data as "instantly stale" — a refetch fires every time the query mounts, every time a component remounts, every time the window regains focus. For data that rarely changes (a product catalog, a user profile, a list of countries), this is a 50x amplification of backend load over what's needed. staleTime tells the cache "trust this data for N seconds — don't refetch within that window."

Pick staleTime based on how often the underlying data changes, not how often the user wants to see updates. A product's name changes monthly; a stock count changes per-second.

Incorrect (default staleTime: refetches on every mount and focus):

function ProductCard({ id }: { id: string }) {
  // staleTime: 0 by default
  // → if the user opens this card in 10 components, focuses the tab,
  //   navigates away and back, you'll see ~12 refetches of /products/:id
  const { data } = useQuery({
    queryKey: ['product', id],
    queryFn: () => fetchProduct(id),
  });
}

Correct (staleTime tuned to data volatility):

function ProductCard({ id }: { id: string }) {
  const { data } = useQuery({
    queryKey: ['product', id],
    queryFn: () => fetchProduct(id),
    staleTime: 5 * 60_000,          // catalog data — fine for 5 minutes
    gcTime: 30 * 60_000,            // keep in memory for 30 min after last use
  });
}

// Different staleTime for different data classes — see [[cache-tiered-stale-fresh]]
function StockBadge({ productId }: { productId: string }) {
  const { data } = useQuery({
    queryKey: ['stock', productId],
    queryFn: () => fetchStock(productId),
    staleTime: 10_000,              // inventory — refresh every 10s
  });
}

Global defaults (set once, override per-query when needed):

new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,            // 30s default — sensible for most app data
      gcTime: 5 * 60_000,
      refetchOnWindowFocus: false,  // opt-in per query
    },
  },
});

Warning: staleTime: Infinity for shared mutable data leaks staleness across users. Reserve it for truly immutable data (a list of country codes).

Reference: TanStack Query — Important Defaults

Centralize Cache Keys in a Key Factory

Key drift is a silent killer: a useQuery reads from ['products', filters] and a mutation invalidates ['product', filters] (singular vs plural). The mutation succeeds, the cache appears intact, the UI shows stale data, and you spend an afternoon debugging "cache invalidation." Define keys once in a typed factory and import them everywhere — reads, writes, prefetches, invalidations all reference the same source of truth.

The factory also gives you free hierarchical invalidation: invalidating productKeys.all invalidates every key starting with ['products', ...].

Incorrect (keys defined inline, easy to drift):

// somewhere in a component
useQuery({ queryKey: ['products', filters], queryFn: () => fetchProducts(filters) });

// in a mutation, six files away
queryClient.invalidateQueries({ queryKey: ['product'] }); // ❌ typo, wrong key
// invalidation looks fine in code review; runtime: nothing invalidates

Correct (one source of truth):

// src/queries/product-keys.ts
export const productKeys = {
  all: ['products'] as const,
  lists: () => [...productKeys.all, 'list'] as const,
  list: (filters: ProductFilters) => [...productKeys.lists(), filters] as const,
  details: () => [...productKeys.all, 'detail'] as const,
  detail: (id: string) => [...productKeys.details(), id] as const,
};

// Reads
useQuery({ queryKey: productKeys.list(filters), queryFn: () => fetchProducts(filters) });
useQuery({ queryKey: productKeys.detail(id), queryFn: () => fetchProduct(id) });

// Mutation — surgical invalidation, no string typos possible
useMutation({
  mutationFn: updateProduct,
  onSuccess: (_, { id }) => {
    queryClient.invalidateQueries({ queryKey: productKeys.detail(id) });
    queryClient.invalidateQueries({ queryKey: productKeys.lists() }); // all list views
  },
});

// Logout — nuke all product queries
queryClient.removeQueries({ queryKey: productKeys.all });

Benefits:

• Type safety: TypeScript catches misuse at compile time
• Refactor confidence: rename a key, every reference updates with editor rename
• Hierarchical invalidation: invalidate at any level (all > lists() > list(filters))
• Single grep location to audit cache structure

Reference: TanStack Query — Effective React Query Keys

Use Stale-While-Revalidate for Instant Renders

The SWR pattern (RFC 5861): when stale data exists, return it instantly and fetch fresh data in the background. The user sees the page immediately, then the cards smoothly update if the fresh data differs. The alternative — showing a skeleton while refetching — punishes the user for already having the data.

Both SWR and TanStack Query implement this; it's the default behavior when staleTime has elapsed but gcTime hasn't. The pattern's superpower: navigating back to a list you've seen renders the list immediately rather than the loading state.

Incorrect (block on revalidation — back-button shows skeleton):

function ProductList() {
  const { data, isLoading } = useQuery({
    queryKey: ['products'],
    queryFn: fetchProducts,
    // No cached data exposed during revalidation
  });
  // After staleTime elapses, isLoading flips true on next mount even though we have data
  if (isLoading) return <Skeleton />; // jarring flicker on every revisit
  return <List products={data!} />;
}

Correct (render stale instantly, fade in fresh):

function ProductList() {
  const { data, isFetching, isPlaceholderData } = useQuery({
    queryKey: ['products'],
    queryFn: fetchProducts,
    staleTime: 60_000,         // 1 min "fresh" window
    placeholderData: keepPreviousData, // for paginated/filtered queries
  });

  // First mount: data is undefined → show skeleton
  // Subsequent mounts: data is the cached value, isFetching may be true → render instantly
  if (!data) return <Skeleton />;
  return (
    <>
      <List products={data} className={isFetching ? 'opacity-90' : ''} />
      {isFetching && <RefreshIndicator />}
    </>
  );
}

For filtered/paginated lists (keep previous results during refetch):

const { data, isPlaceholderData } = useQuery({
  queryKey: ['products', { filter }],
  queryFn: () => fetchProducts(filter),
  placeholderData: keepPreviousData, // when filter changes, show old results until new ones land
});
// Filtering doesn't flash an empty state; only after new data resolves does the list update.

Server-side equivalent (HTTP header):

Cache-Control: public, max-age=0, stale-while-revalidate=600
# Browser/CDN serves stale data instantly and revalidates in the background up to 10 min

Reference: Vercel — Stale-While-Revalidate | RFC 5861

Tier staleTime by Data Volatility

One global staleTime is a compromise — too high for inventory (shows out-of-date stock), too low for the country list (refetched needlessly). Classify your data by volatility class and assign each class a staleTime. Real-time data (stock, price) gets seconds; user profile gets minutes; catalog/lookup data gets hours.

This tiering is also what HTTP caching does well — Cache-Control: max-age per endpoint type. Mirror that policy in your client cache.

Incorrect (one global staleTime — fights everything):

new QueryClient({
  defaultOptions: { queries: { staleTime: 30_000 } },
});
// Inventory shown 30s stale → user adds to cart, gets "out of stock" at checkout
// Country list refetched every 30s → 100k pointless requests/day across users

Correct (tiered, per data class):

// src/queries/stale-tiers.ts
export const STALE = {
  realtime: 5_000,       //   5s — stock, live price, online status
  fresh:    30_000,      //  30s — feed, notifications, cart contents
  warm:     5  * 60_000, //   5m — user profile, settings, preferences
  cold:     60 * 60_000, //   1h — product details, posts, comments
  static:   24 * 60 * 60_000, // 24h — country list, categories, tag taxonomy
} as const;

useQuery({ queryKey: ['stock', id], queryFn: () => fetchStock(id), staleTime: STALE.realtime });
useQuery({ queryKey: ['user', id],  queryFn: () => fetchUser(id),  staleTime: STALE.warm });
useQuery({ queryKey: ['countries'], queryFn: fetchCountries,       staleTime: STALE.static });

Pair with server Cache-Control headers for full-stack consistency:

// API route handler
response.headers.set('Cache-Control', 'public, max-age=5, stale-while-revalidate=30'); // stock
response.headers.set('Cache-Control', 'public, max-age=300, stale-while-revalidate=600'); // user
response.headers.set('Cache-Control', 'public, max-age=86400, immutable'); // countries

How to pick a tier: look at the underlying source of truth. If it's a metric that updates per-second, use realtime. If it's a user-editable field, warm to cold. If it's reference data deployed with the app, static.

Reference: TkDodo — staleTime vs gcTime

Bound the In-Memory Working Set on Long Feeds

A user who scrolls through 50 pages of a feed accumulates 50 pages × 30 items = 1500 cached items, even with virtualization. The DOM is bounded by virtualization, but the JS heap is not — image objects, cached query results, and normalized entity records grow without limit. On mobile, this triggers OOM kills; on desktop, GC pauses cause scroll jank.

Bound the cache: after page N+5, drop the oldest pages from the infinite-query cache and the entity store. The user can always re-scroll; the entities they care about (favorites, viewed items) are kept separately.

Incorrect (unbounded growth — JS heap balloons on long scroll):

function Feed() {
  const { data } = useInfiniteQuery({
    queryKey: ['feed'],
    queryFn: ({ pageParam }) => fetchFeedPage(pageParam),
    initialPageParam: null,
    getNextPageParam: last => last.nextCursor,
    // No maxPages — pages accumulate forever
  });
}

Correct (bounded with maxPages — old pages drop as new ones load):

function Feed() {
  const { data } = useInfiniteQuery({
    queryKey: ['feed'],
    queryFn: ({ pageParam }) => fetchFeedPage(pageParam),
    initialPageParam: null,
    getNextPageParam: last => last.nextCursor,
    getPreviousPageParam: first => first.prevCursor,
    maxPages: 8, // keep at most 8 pages × 30 items = 240 items in memory
  });
  // When fetchNextPage exceeds maxPages, the oldest page is dropped from data.pages
  // If the user scrolls back, fetchPreviousPage refetches it
}

Pair virtualization with cache eviction (memory-bounded scroll without losing position):

function BoundedFeed() {
  const parentRef = useRef<HTMLDivElement>(null);
  const { data, fetchNextPage, fetchPreviousPage, hasNextPage, hasPreviousPage } =
    useInfiniteQuery({ /* ...with maxPages: 8, getPreviousPageParam ... */ });

  const allItems = data?.pages.flatMap(p => p.items) ?? [];

  const virtualizer = useVirtualizer({
    count: allItems.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 120,
    overscan: 5,
    // When the user scrolls UP past the start of cached pages, fetch previous
    onChange: (instance) => {
      const first = instance.getVirtualItems()[0];
      if (first && first.index < 5 && hasPreviousPage) fetchPreviousPage();
    },
  });
}

For normalized entity stores (cap by recency + pinning):

// Pseudocode: LRU eviction with pinned items
class EntityStore<T extends { id: string }> {
  private items = new Map<string, T>();
  private order: string[] = [];     // most-recent first
  private pinned = new Set<string>(); // never evict (favorites, recently-viewed)

  constructor(private maxSize: number) {}

  set(id: string, value: T) {
    this.items.set(id, value);
    this.order = [id, ...this.order.filter(i => i !== id)];
    this.evict();
  }

  pin(id: string) { this.pinned.add(id); }

  private evict() {
    while (this.order.length > this.maxSize) {
      const candidate = [...this.order].reverse().find(id => !this.pinned.has(id));
      if (!candidate) break;
      this.items.delete(candidate);
      this.order = this.order.filter(i => i !== candidate);
    }
  }
}

Mobile-specific consideration: iOS Safari kills tabs at ~1GB JS heap. Native apps see OS-level memory warnings at ~150MB. Bound the working set aggressively on mobile: maxPages: 4 instead of 8, no large blurred-image placeholders.

Image-specific cleanup: even when items drop from the data cache, the browser may keep image bitmaps. For very long-running feeds, periodically clear URL.revokeObjectURL for blob: URLs you created, and avoid keeping references to image elements.

Reference: TanStack Query — maxPages

Use Cursor Pagination over Offset

Offset pagination (?page=2&size=20 or LIMIT 20 OFFSET 40) has two problems at scale: (1) the backend re-scans rows 0-39 just to return rows 40-59 — OFFSET 100000 is brutal on the database; (2) when new items are inserted between page fetches (very common in feeds), the user sees duplicate or skipped items because page boundaries shift. Cursor pagination uses an opaque cursor pointing to "the item after which to continue" — stable across inserts, indexable, fast.

Use cursors for any feed where new items can appear between page fetches.

Incorrect (offset pagination — duplicates and skips on inserts):

async function fetchFeedPage(page: number): Promise<{ items: Post[]; nextPage: number | null }> {
  const res = await fetch(`/api/feed?page=${page}&size=20`);
  return res.json();
}

// Backend: SELECT * FROM posts ORDER BY created_at DESC LIMIT 20 OFFSET ${page*20}
// User loads page 1 (newest 20 posts), then 5 new posts come in,
// then user loads page 2 — they see the last 5 from page 1 again

Correct (cursor pagination — stable across inserts):

type FeedPage = { items: Post[]; nextCursor: string | null };

async function fetchFeedPage(cursor: string | null): Promise<FeedPage> {
  const params = new URLSearchParams({ size: '20' });
  if (cursor) params.set('cursor', cursor);
  const res = await fetch(`/api/feed?${params}`);
  return res.json();
}

// Backend: SELECT * FROM posts WHERE created_at < ${cursor_date} ORDER BY created_at DESC LIMIT 20
// New inserts at the top don't shift the cursor's anchor point

With TanStack Query's useInfiniteQuery:

function Feed() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
    queryKey: ['feed'],
    queryFn: ({ pageParam }) => fetchFeedPage(pageParam),
    initialPageParam: null as string | null,
    getNextPageParam: lastPage => lastPage.nextCursor,
  });

  const allItems = data?.pages.flatMap(p => p.items) ?? [];
  // Items deduplicate cleanly across pages because cursors don't overlap
}

Backend implementation patterns:

-- Cursor as a composite: (created_at, id) for tie-breaking
SELECT * FROM posts
WHERE (created_at, id) < ($cursorTime, $cursorId)
ORDER BY created_at DESC, id DESC
LIMIT 21; -- fetch one extra to detect "has next"

-- Encode cursor opaquely so clients can't manipulate it:
-- cursor = base64({ created_at, id })

For real-time feeds (poll the "head" cursor):

// Periodically check for new items above the top — a "newer than cursor X" query
const { data: newItems } = useQuery({
  queryKey: ['feed', 'newer-than', headCursor],
  queryFn: () => fetchNewerThan(headCursor),
  refetchInterval: 30_000,
  enabled: !!headCursor,
});
// Surface as "5 new posts — tap to view" badge instead of inserting mid-scroll

When offset is fine:

• Stable archives (blog post lists that don't change)
• Admin tables with deterministic sort + low insert rate
• Small data sets where OFFSET performance doesn't matter

Pitfall (don't expose internal DB IDs as cursors): if your cursor is ?cursor=12345, users learn that posts are sequential integers and probe gaps. Use opaque, signed cursors.

Reference: Use The Index, Luke — Pagination | TanStack Query — Infinite Queries

Defer Off-Screen Feed Images with Explicit Dimensions

A feed of 100 items each with a 200kb hero image means a 20MB download if everything loads up front — but most users scroll through ~10 items. Native loading="lazy" defers off-screen images until the user scrolls near them. Explicit width and height (or aspect-ratio) prevent layout shift when each image arrives — without dimensions, the page jumps as images load, breaking infinite scroll.

<img loading="lazy"> is supported in all evergreen browsers. For finer control, combine IntersectionObserver with a low-quality placeholder.

Incorrect (eager-load all images, no dimensions, layout shifts as they arrive):

function FeedItem({ item }: { item: Item }) {
  return (
    <article>
      <img src={item.heroUrl} alt={item.title} />
      {/* No width/height — height is 0 until image loads, then expands and pushes everything */}
      <h3>{item.title}</h3>
    </article>
  );
}
// 100 items × 200kb = 20MB download on mount; CLS score destroyed

Correct (lazy-loaded with explicit aspect ratio):

function FeedItem({ item }: { item: Item }) {
  return (
    <article>
      <img
        src={item.heroUrl}
        alt={item.title}
        width={1200}
        height={630}
        loading="lazy"
        decoding="async"
        style={{ aspectRatio: '1200 / 630', objectFit: 'cover', width: '100%', height: 'auto' }}
      />
      <h3>{item.title}</h3>
    </article>
  );
}
// Only images near viewport download; layout stable as images arrive

With Next.js Image (optimized + lazy + responsive):

import Image from 'next/image';

function FeedItem({ item }: { item: Item }) {
  return (
    <article>
      <Image
        src={item.heroUrl}
        alt={item.title}
        width={1200}
        height={630}
        sizes="(max-width: 768px) 100vw, 720px" // serve appropriately sized image
        loading="lazy"
        placeholder="blur"
        blurDataURL={item.heroBlur} // tiny inline placeholder (~100 bytes)
      />
    </article>
  );
}

For the first 1-3 items above the fold, eager-load:

{items.map((item, i) => (
  <FeedItem
    key={item.id}
    item={item}
    priority={i < 2} // first two get loading="eager" and fetchpriority="high"
  />
))}

For carousels (off-screen but DOM-rendered):

// Native loading="lazy" only triggers on viewport intersection;
// horizontally-scrolled carousel items count as "in viewport" even when scrolled away
// → use IntersectionObserver on the carousel container instead

Avoid CLS pitfalls:

Reference: MDN — Lazy loading | web.dev — Cumulative Layout Shift

Isolate Failure Across a Feed of Carousels

A homepage feed of 6 carousels (trending, recommended, recently-viewed, "people also bought", seasonal, personalized) means 6 independent recommender pipelines. At any given moment, one of them is degraded — a model is being redeployed, a data source is rate-limited, a personalization service is on call. Without isolation, one failing carousel cascades to break the whole feed (one Suspense root → all wait for the slowest; one ErrorBoundary root → one failure crashes everything).

The pattern: wrap each carousel in its own ErrorBoundary + Suspense, tier carousels by importance (critical, important, decorative), and apply tier-appropriate fallbacks. Combine with bounded concurrency at the fetch layer so 6 parallel summary fetches don't drown the user-initiated request happening at the same time.

This is the multi-section version of [[resilience-scoped-error-boundaries]] and [[render-suspense-per-section]], with the failure-tier logic from [[resilience-graceful-degradation]].

Incorrect (single boundary — one failure kills the entire feed):

function HomepageFeed() {
  return (
    <ErrorBoundary fallback={<FullPageError />}>
      <Suspense fallback={<FullFeedSkeleton />}>
        <ContinueWatchingCarousel />
        <RecommendedCarousel />
        <TrendingCarousel />
        <RecentlyViewedCarousel />     {/* this one errors */}
        <SeasonalCarousel />
        {/* → entire homepage now shows FullPageError because one decorative
             carousel had a 500. User sees nothing. */}
      </Suspense>
    </ErrorBoundary>
  );
}

Correct (per-carousel isolation with tier-appropriate fallbacks):

type Tier = 'critical' | 'important' | 'decorative';

const FEED: Array<{ kind: string; title: string; tier: Tier }> = [
  { kind: 'continue-watching', title: 'Continue watching',  tier: 'critical' },
  { kind: 'recommended',       title: 'Recommended for you', tier: 'important' },
  { kind: 'trending',          title: 'Trending now',        tier: 'important' },
  { kind: 'recently-viewed',   title: 'Recently viewed',     tier: 'decorative' },
  { kind: 'seasonal',          title: 'Seasonal picks',      tier: 'decorative' },
];

function HomepageFeed() {
  return (
    <div className="flex flex-col gap-12">
      {FEED.map((cfg, i) => (
        <ErrorBoundary
          key={cfg.kind}
          onError={(e) => reportError({ section: cfg.kind, tier: cfg.tier, error: e })}
          fallbackRender={({ resetErrorBoundary }) => {
            if (cfg.tier === 'decorative') return null;                   // silent
            if (cfg.tier === 'important')  return <MiniError onRetry={resetErrorBoundary} />;
            return <FullError title={cfg.title} onRetry={resetErrorBoundary} />;
          }}
        >
          <Suspense fallback={<CarouselSkeleton title={cfg.title} />}>
            {i < 2
              ? <Carousel kind={cfg.kind} />        // above the fold — eager
              : <DeferredCarousel kind={cfg.kind} />} // below the fold — viewport-triggered
          </Suspense>
        </ErrorBoundary>
      ))}
    </div>
  );
}

Eager and deferred carousel variants:

// Above-the-fold — suspends on first fetch
function Carousel({ kind }: { kind: string }) {
  const { data } = useSuspenseQuery({
    queryKey: ['carousel', kind, 'summaries'],
    queryFn: ({ signal }) => fetchCarouselSummaries(kind, { signal }),
    staleTime: 5 * 60_000,
  });
  return <Track items={data} />;
}

// Below-the-fold — defer mounting (and fetching) until in viewport
function DeferredCarousel({ kind }: { kind: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const [visible, setVisible] = useState(false);
  useEffect(() => {
    const obs = new IntersectionObserver(
      ([e]) => e.isIntersecting && setVisible(true),
      { rootMargin: '300px' }
    );
    if (ref.current) obs.observe(ref.current);
    return () => obs.disconnect();
  }, []);
  if (!visible) return <div ref={ref} style={{ height: 280 }} />; // reserve space
  return <div ref={ref}><Carousel kind={kind} /></div>;
}

Tier fallbacks table:

Concurrency guardrail at the fetch layer:

Six carousels mounting at once means six parallel summary requests, plus dozens of detail prefetches if items hover-prefetch. Cap parallelism so the feed degrades to "smooth but a bit slower" instead of "all timing out":

// At fetch wiring time — see [[protect-concurrency-limit-fanout]]
import { collapsedFetch } from './request-collapser';
// collapsedFetch caps at 6 concurrent requests + dedupes identical GETs
async function fetchCarouselSummaries(kind: string, init: { signal: AbortSignal }) {
  const res = await collapsedFetch(`/api/carousels/${kind}/summaries`, init);
  return res.json();
}

Render-priority ordering matters:

Even with per-section Suspense, render order in the JSX determines reveal order in the SSR streaming case. Put critical carousels first — they get the first reserved layout slot and the first streamable chunk. Decorative carousels last, so their slow data sources don't push the critical ones below the fold.

Observability rule: silent failures are not invisible failures. Decorative carousels rendering null on failure must still emit a structured error to your logging stack (onError={reportError}) so an outage is detectable. A degraded recommender that quietly serves zero items for a week is a silent revenue leak.

When NOT to use this pattern:

• Single-carousel pages — the overhead of tiering buys nothing
• Synchronously-loaded feeds where every carousel ships in the initial HTML payload — Suspense isn't doing meaningful work
• Critical compliance flows where ANY missing data is a hard fail — there tier: critical isn't strong enough; refuse to render the page at all

Pair with [[feed-split-summary-from-detail]]: each carousel's summary fetch returns lightweight payloads; viewport-triggered detail fetches keep working-set bounded across the whole feed.

Reference: react-error-boundary | Vercel — Streaming with Suspense

Split Carousel Summaries from Item Details

A recommender carousel needs very little per item to render: ID, thumbnail URL, title, often a price. But the same backend endpoint often returns the full product object — description, variants, reviews, related products — bloating the payload. Split the API: one endpoint returns lightweight summaries (10x smaller); detail endpoints fetch the rest on hover, click, or viewport.

For carousel-heavy pages, this is the difference between a 200kb response and a 20kb response — and the difference between fetching 30 detail-laden objects for items 90% of users never click.

Incorrect (carousel fetches full objects up front):

function RecommendedCarousel() {
  const { data } = useQuery({
    queryKey: ['recs', 'full'],
    queryFn: fetchFullRecommendations, // returns full product objects: 80kb for 30 items
  });
  return (
    <Carousel>
      {data?.map(p => (
        <CarouselCard key={p.id} thumbnail={p.thumbnail} title={p.title} />
        // Each card uses 3 fields out of ~25 — the other 22 fields are wasted bytes
      ))}
    </Carousel>
  );
}

Correct (summary + on-demand detail):

// Summary type: just what the card renders
type ProductSummary = { id: string; thumbnail: string; title: string; price: number };

function RecommendedCarousel() {
  const { data: summaries } = useQuery({
    queryKey: ['recs', 'summary'],
    queryFn: fetchRecommendationsSummary, // returns ProductSummary[]: 5kb for 30 items
  });

  return (
    <Carousel>
      {summaries?.map(s => (
        <CarouselCard
          key={s.id}
          summary={s}
          // Pre-fetch full detail on hover; quick-look popover uses it instantly
          onMouseEnter={() => queryClient.prefetchQuery({
            queryKey: ['product', s.id],
            queryFn: () => fetchProduct(s.id),
            staleTime: 60_000,
          })}
        />
      ))}
    </Carousel>
  );
}

// When the user clicks for a quick-look
function QuickLook({ productId }: { productId: string }) {
  const { data: product } = useQuery({
    queryKey: ['product', productId],
    queryFn: () => fetchProduct(productId),
  });
  return <DetailView product={product} />;
}

API endpoint design pattern:

GET /api/recommendations
  → returns [{ id, thumbnail, title, price }, ...]   # 5kb for 30 items

GET /api/products/:id
  → returns full product object                       # 4kb for one item

GET /api/products?ids=a,b,c
  → returns full product objects, bulk                # 4kb × N for batched detail

For carousels with viewport-triggered detail (only items the user sees get detailed):

function CarouselCard({ summary }: { summary: ProductSummary }) {
  const cardRef = useRef<HTMLDivElement>(null);
  const [inViewport, setInViewport] = useState(false);

  useEffect(() => {
    const obs = new IntersectionObserver(([e]) => setInViewport(e.isIntersecting));
    if (cardRef.current) obs.observe(cardRef.current);
    return () => obs.disconnect();
  }, []);

  // Only fetch detail for items the user actually scrolls past
  const { data: detail } = useQuery({
    queryKey: ['product', summary.id],
    queryFn: () => fetchProduct(summary.id),
    enabled: inViewport,
    staleTime: 60_000,
  });

  return <div ref={cardRef}>{/* render summary; show detail extras when present */}</div>;
}

When NOT to split: if the summary is already most of the object (a tweet has very few fields beyond the visible content), the split costs more than it saves.

Cache normalization angle: when summaries and details overlap on the same fields (title, thumbnail), pair this with [[cache-normalize-shared-entities]] so fetching the detail upgrades the summary in place rather than holding two copies.

Reference: GraphQL — Fragments and Field Selection | Vercel — Optimizing Data Fetching

Use Stable Item Keys Across Paginated Pages

In a paginated/infinite feed, every time a new page arrives the parent re-renders with a longer items array. If item keys are stable (item.id), React reconciles in O(N+1) — existing rows reuse their fibers, only the new ones mount. If keys are index-based (key={i}), every row "moves" when the array grows from prepending or when virtual indices shift, triggering a full unmount/remount of every visible row.

Mount/unmount cycles re-trigger effects (refetches), re-create child query subscriptions, and reset internal state (form inputs, scroll positions inside items). For high-frequency feeds, key instability is a silent 5-10× cost multiplier on scroll updates.

Incorrect (index keys — entire list unmounts/remounts on new pages):

function Feed() {
  const { data } = useInfiniteQuery({/* ... */});
  const items = data?.pages.flatMap(p => p.items) ?? [];

  return items.map((item, i) => <FeedRow key={i} item={item} />);
  // After a "prepend new items" event, every existing row sees a different key
  // → every row remounts → every embedded useQuery refires → every form resets
}

Correct (entity ID keys — stable across mutations):

function Feed() {
  const { data } = useInfiniteQuery({/* ... */});
  const items = data?.pages.flatMap(p => p.items) ?? [];

  return items.map(item => <FeedRow key={item.id} item={item} />);
  // Even when 5 new items are prepended, the existing rows keep their fibers
}

For items without natural IDs (e.g., aggregated rows in a report):

// Generate a stable composite key on the data side, not in render
const itemsWithKeys = useMemo(
  () => items.map(item => ({ ...item, key: `${item.userId}-${item.date}` })),
  [items]
);

// In render:
itemsWithKeys.map(item => <Row key={item.key} item={item} />);

De-duplicate items across pages (cursor pagination can produce repeats at page edges):

const items = useMemo(() => {
  const all = data?.pages.flatMap(p => p.items) ?? [];
  // Dedup by id, keep first occurrence
  const seen = new Set<string>();
  return all.filter(item => seen.has(item.id) ? false : (seen.add(item.id), true));
}, [data]);

Symptoms of unstable keys (debug checklist):

• Forms inside list items lose their input on every refresh
• Embedded queries refetch on every page load
• Animations restart on every parent update
• React DevTools shows mount/unmount on rows that visually stayed in place

Don't use random IDs: key={Math.random()} or key={crypto.randomUUID()} generated in render means every render produces new keys → every row remounts every render. This is the most extreme version of the bug.

Reference: React — Keeping list items in order with key