Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 132 ยท Data and Async

Caching and Server State

Understand server state in React - stale-while-revalidate, query keys, deduping, invalidation - by building a tiny query cache, then see how TanStack Query and SWR do it.

Most of the data in a typical app is not really yours. A product list, a user profile, a dashboard number: they live on a server, you only hold a copy, and that copy can be out of date the moment it arrives. That makes server state a different kind of thing from the state in useState, such as whether a menu is open. Server state is remote, shared, asynchronous, and can change without you knowing.

The effect-based approach from Fetching Data works for one component, but it leaves a lot of problems to you: two components asking for the same data send two requests, navigating away and back shows a spinner again, and after a save you have to refetch by hand. The remedy is a cache that sits between your components and the network. In this lesson you build a small one so the ideas stop being magic, and then see how the big libraries package them.

The problems a cache solves

Start with the naive version. Two components need the same user. Each one runs its own effect.

Without a cache: duplicate requests

Open the console. On load it shows request: user 1 twice, one per component, for identical data. Click Hide sidebar and then Show sidebar: the sidebar remounts, its effect runs again, and a third request: user 1 appears, plus the "Loading..." flash, even though we fetched this exact user a moment ago.

A cache fixes this class of problems with a handful of ideas.

The four ideas

1. Query keys. Every piece of server data gets a key that names it, such as ['user', 1] or ['todos', { filter: 'done' }]. The key is the address in the cache. Same key, same data; a different parameter means a different key and a different entry. Because the key contains everything the request depends on, you never need to clear the cache when the user switches from user 1 to user 2: they are different entries.

2. Deduping. If a request for a key is already in flight, a second component asking for the same key joins it instead of sending another request.

3. Stale-while-revalidate (SWR). Cached data is shown immediately, even though it might be old (stale), and a fresh request runs in the background. When it returns, the screen updates. The user sees content instantly, and it fixes itself. This is where the SWR library gets its name.

4. Invalidation. After a change (you saved a todo), you mark related keys as stale. Any component currently showing them refetches.

Two more concepts appear in libraries: staleTime, how long data counts as fresh before a revisit triggers a refetch, and garbage collection, how long unused entries stay in memory.

Building a mini query cache

React gives us exactly one hook for reading data from an outside store safely: useSyncExternalStore. It subscribes a component to a store that lives outside React and re-renders it when the store changes (more in External Stores). Our cache is that store.

Here is the whole library. Read it from the top; it is under 60 lines.

JavaScript
const cache = new Map();      // key string -> entry
const inFlight = new Map();   // key string -> promise
const observers = new Map();  // key string -> { count, fn }
const listeners = new Set();
const EMPTY = Object.freeze({ status: 'pending', data: undefined, error: undefined, isFetching: false, isStale: true });

const toKey = (key) => JSON.stringify(key);
const getEntry = (k) => cache.get(k) ?? EMPTY;

function setEntry(k, patch) {
  cache.set(k, { ...getEntry(k), ...patch });
  listeners.forEach((listener) => listener());
}

function fetchQuery(k, fn) {
  if (inFlight.has(k)) return inFlight.get(k);          // deduping
  setEntry(k, { isFetching: true });
  const promise = fn()
    .then((data) => setEntry(k, { status: 'success', data, error: undefined, isFetching: false, isStale: false }))
    .catch((error) => setEntry(k, { status: 'error', error, isFetching: false }))
    .finally(() => inFlight.delete(k));
  inFlight.set(k, promise);
  return promise;
}

function invalidate(prefix) {
  const start = JSON.stringify(prefix).slice(0, -1);    // ["todos"] -> ["todos"
  for (const k of [...cache.keys()]) {
    if (!k.startsWith(start)) continue;
    setEntry(k, { isStale: true });
    const observer = observers.get(k);
    if (observer && observer.count > 0) fetchQuery(k, observer.fn);
  }
}

function useQuery(key, fn) {
  const k = toKey(key);
  const entry = useSyncExternalStore(
    (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
    () => getEntry(k)
  );
  useEffect(() => {
    const observer = observers.get(k) ?? { count: 0, fn };
    observer.count += 1;
    observer.fn = fn;
    observers.set(k, observer);
    if (getEntry(k).isStale) fetchQuery(k, fn);         // SWR: refetch, keep showing old data
    return () => { observer.count -= 1; };
  }, [k]);
  return entry;
}

Walk through the design:

  • An entry holds status, data, error, isFetching and isStale. status is about whether we have ever had data; isFetching is about whether a request is running now. They are separate on purpose: an entry can have status: 'success' (data on screen) and isFetching: true (refreshing in the background). That separation is the heart of stale-while-revalidate.
  • setEntry replaces the entry object with a new one and tells every listener. useSyncExternalStore compares snapshots with Object.is, so returning the same object until something changes is essential. The shared EMPTY constant is the same trick for keys that have no entry yet.
  • fetchQuery is the only place that talks to the network. Its first line is the dedupe.
  • invalidate accepts a prefix: invalidate(['todos']) marks ['todos'] and ['todos', 'done'] stale, and refetches those that are on screen.
  • useQuery reads the entry and, in an effect, registers itself as an observer and triggers a fetch if the entry is stale. The effect depends on the key string, so changing the parameter switches entries.

Deduping and keys in action

Mini cache: one request for two components

On load the console shows a single request: user 1, although Header and Sidebar both ask for it. Press User 2: one request: user 2, and the sidebar changes while the header keeps its data. Press User 1 again and no new request is logged, because ["user",1] is already in the cache and not stale. Our simple cache has no expiry, so cached entries stay fresh until you invalidate them; the next example revalidates on every mount instead.

Stale-while-revalidate

Now the most visible feature. The server below returns a different version number on every request, so you can see when you are looking at cached data and when it was refreshed. Hide and show the panel: the panel unmounts, the cache survives, and on the next show the old data appears instantly while a new request runs.

Mini cache: show stale data, then refresh

Here is what our run logged. The first mount renders with status=pending (nothing cached yet), then request: stats (server version 1), then status=success, visitors=100, isFetching=false. After Hide and Show, the panel renders status=success, visitors=100, isFetching=false at once, which is the cached value, with no loading state. Then comes request: stats (server version 2), a render with visitors=100, isFetching=true (the panel reads Visitors: 100 (refreshing...)), and finally visitors=200, isFetching=false.

That second visit is the whole point: the user is never staring at a spinner for data you already have. Stale-while-revalidate trades a short moment of possibly outdated data for instant feedback.

Invalidation after a change

When the user changes server data, the cached copy is wrong. The mutation tells the server, then calls invalidate, and every on-screen query under that key refetches.

Mini cache: invalidate after a mutation

Press Add todo. The console shows request: GET todos (2 on server) on load, then request: POST todo "Todo number 3", then request: GET todos (3 on server). Both Total todos: 3 and the list update, and there was only one GET after the POST although two components display the todos (deduping).

One invalidate(['todos']) updated two separate components, because both read the same key. That decoupling is the real benefit: the code that saves does not need to know who displays the data.

What the libraries add

Our mini cache handles the happy path. Production libraries add years of edge cases: retries with backoff, request cancellation, refetch when the window regains focus or the network reconnects, garbage collection of unused entries, pagination and infinite lists, optimistic updates with rollback, devtools, SSR hydration, and well-tested behavior in StrictMode and concurrent rendering. In real projects use one of them. These two are the most common; the snippets are read-only because the packages are not available in our editor.

TanStack Query (formerly React Query):

JSX
import { QueryClient, QueryClientProvider, useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient();

function Todos() {
  const queryClient = useQueryClient();
  const { data, isPending, isFetching, error } = useQuery({
    queryKey: ['todos'],
    queryFn: () => fetch('/api/todos').then((response) => response.json()),
    staleTime: 30_000,   // fresh for 30 seconds; the default is 0
  });

  const addTodo = useMutation({
    mutationFn: (title) => fetch('/api/todos', { method: 'POST', body: JSON.stringify({ title }) }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
  });

  if (isPending) return <p>Loading...</p>;
  if (error) return <p>Failed: {error.message}</p>;
  // render data, call addTodo.mutate('...')
}

SWR:

JSX
import useSWR, { mutate } from 'swr';

const fetcher = (url) => fetch(url).then((response) => response.json());

function Profile() {
  const { data, error, isLoading, isValidating } = useSWR('/api/user', fetcher);
  // after a change elsewhere:  mutate('/api/user')
}

The vocabulary maps one to one onto what you built: queryKey is our key, isFetching is our isFetching, invalidateQueries is our invalidate, and SWR's isValidating is the same flag again. Both refetch on window focus by default. TanStack Query's staleTime controls how long data counts as fresh and its gcTime (five minutes by default) controls how long unused entries stay in memory.

Frameworks such as Next.js and React Router bring their own data loading and caching, and can also stream promises into use and Suspense. Understanding the four ideas above transfers to all of them.

Server state versus client state

A rule of thumb that prevents a lot of confusion:

  • Server state (data owned by a backend) belongs in a query cache. Do not copy it into useState or a global store "so it is available everywhere"; the copy goes stale and you must keep it in sync by hand.
  • Client state (open dialogs, form drafts, selected tabs) belongs in useState, reducers, context or a client store; see State Management.
  • Forms are the bridge: keep the draft in client state, send it with a mutation, then invalidate.

Common pitfalls

  • Keys that miss a dependency. If fetchUser uses id and locale but the key is ['user', id], two locales share one cache entry. The key must contain every input to the request.
  • Unstable keys. JSON.stringify of an object with a different property order produces a different string. Libraries hash keys in a stable way; our mini cache does not, so keep key objects consistent.
  • Mutating cached data. The cache returns the same object to everyone. Never edit data in place; copy it.
  • Over-invalidating. Invalidating [] refetches everything. Be as specific as the change.
  • Treating the cache as a database. It is a performance layer. The server stays the source of truth.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the purpose of a query key?

    The key is the address of the data in the cache. It must include every value the request depends on.
  2. 2. What does stale-while-revalidate do?

    The user sees something instantly; when the background request returns, the screen updates.
  3. 3. Two components call useQuery with the same key while a request is in flight. How many requests are sent?

    Deduping returns the existing promise for that key instead of starting another request.
  4. 4. After saving a todo on the server, what should you do with the cached list?

    Invalidation marks matching entries stale and refetches the ones in use. The code that saves does not need to know which components show the list.
  5. 5. Why does useSyncExternalStore need getSnapshot to return the same object until the store changes?

    A new object on every call looks like a change on every check. Replace the entry object only when the data really changes.

Summary

  • Server state is a remote, shared, possibly outdated copy of data; it deserves a cache rather than scattered useState and effects.
  • A query key addresses each entry. Include every input of the request in it.
  • Deduping shares one in-flight request; stale-while-revalidate shows cached data first and refreshes in the background; invalidation marks entries stale after a change.
  • status (do we have data) and isFetching (is a request running) are separate flags.
  • useSyncExternalStore connects an outside store to React; snapshots must be referentially stable between changes.
  • In real projects use TanStack Query, SWR or your framework's data layer; the concepts here map directly onto them.

Next: Async Patterns and Race Conditions