Data fetching libraries

One product, asked for again and again

In Fetching data you loaded a product in an effect, with a cleanup, a loading state, and an error state. Here that code is moved into a custom hook, useProduct, and two parts of a product page use it: the title and a stock badge. The server is pretend, in the api.js tab: it answers after 0.8 seconds, nothing goes over the network, and other shoppers buy a tea every 4 seconds, so the stock goes down. Open the console under the result.

1import { useEffect, useState } from "react";2import { fetchProduct } from "./api.js";3 4function useProduct(id) {5  const [product, setProduct] = useState(null);6  useEffect(() => {7    let ignore = false;8    fetchProduct(id).then((data) => {9      if (!ignore) setProduct(data);10    });11    return () => {12      ignore = true;13    };14  }, [id]);15  return product;16}17 18function ProductTitle() {19  const product = useProduct("tea");20  return <h2>{product ? product.name : "Loading…"}</h2>;21}22 23function StockBadge() {24  const product = useProduct("tea");25  return <p>{product ? `${product.stock} left` : "Loading…"}</p>;26}27 28export default function App() {29  const [open, setOpen] = useState(true);30  return (31    <>32      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>33      {open && (34        <>35          <ProductTitle />36          <StockBadge />37        </>38      )}39    </>40  );41}

Lines 4 to 16 are the effect from the last lesson: state for the product, a request, and an ignore flag in the cleanup. ProductTitle calls the hook on line 19, and StockBadge calls it again on line 24. The console says Request 1 to Request 4: each component sends its own request, and StrictMode runs each new effect twice in development, so two components make four. In production it would be two, for one product.

Now press Hide the product, then Show the product. Both lines say Loading… for 0.8 seconds again, and the console counts four more requests. Hiding removed the components, and their state went with them, so the product you just saw is gone. A real app has this everywhere: a header, a list, and a details page all asking for the same things, and every visit starting from nothing.

The picture shows why this keeps happening. The product isn't the page's data at all. The server holds it, and the page holds a copy from the moment it asked. That copy needs work that useState doesn't do: sharing it between components, keeping it after they leave, and asking again when it may be old. A data fetching library, such as TanStack Query or SWR, does that work for every request in the app.

Server state is a copy you borrowed

React lessons so far kept data in state: a tab, a count, the text in a box. That's client state: it lives in this page, and only this page changes it. Data that comes from a server is different, and it has a name of its own, server state. Here are both in one component:

function ProductPage() {
  // Client state: only this page has it, and only you change it.
  const [tab, setTab] = useState("details");
  const [quantity, setQuantity] = useState(1);

  // Server state: a copy of what the server said, the last time you asked.
  const { data: product } = useQuery({
    queryKey: ["product", "tea"],
    queryFn: () => fetchProduct("tea"),
  });
  // …
}

Lines 3 and 4 are client state: the tab you picked and the quantity you chose. Nothing outside this page knows about them. Lines 7 to 10 are server state, read with a useQuery hook like the one you build in the next section. The product it gives back is a copy of what the server said the last time anyone asked. It's a fragment, so it isn't live; the rest of the lesson runs every piece of it.

How to read the table: each row is one question, answered for each kind of state.

Every "yes" in the server column is work: a loading state while you wait, an error state when it fails, and some way to tell when the copy is too old. Libraries for server state do that work. They don't replace useState: the tab and the quantity stay in useState, as before.

A toy cache: one entry per query key

The best way to see what a library does is to build a small one. The cache.js tab below is a toy: about forty lines, written for this lesson, with none of the care a real library takes. Don't use it in an app; use it to see the idea. It names its function useQuery and its options queryKey and queryFn, as TanStack Query does, so the real thing looks familiar later.

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9  });10}11 12function ProductTitle() {13  const { data, isPending } = useProduct("tea");14  return <h2>{isPending ? "Loading…" : data.name}</h2>;15}16 17function StockBadge() {18  const { data, isPending } = useProduct("tea");19  return <p>{isPending ? "Loading…" : `${data.stock} left`}</p>;20}21 22export default function App() {23  const [open, setOpen] = useState(true);24  return (25    <>26      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>27      {open && (28        <>29          <ProductTitle />30          <StockBadge />31        </>32      )}33    </>34  );35}

In App.jsx, useProduct is now one call (lines 5 to 10). Line 7 gives the data a name, the query key: ["product", id]. Line 8 says how to get it. The console says Request 1: product tea and nothing more: two components, StrictMode, one request. Press Hide and Show: the product is back at once, with no Loading… and no request. Here is how, in the cache.js tab:

• Line 4 makes the cache, a Map from keys to entries. It lives in the module, outside every component, so it stays when the components leave.
• save on lines 13 to 16 replaces a key's entry with a new object and tells every listener. A new object each time is what useSyncExternalStore needs to see a change.
• fetchQuery on lines 18 to 25 asks the server for a key. Line 19 returns early when that key already has a request going: that's deduplication, sharing one request between everyone who asks. Line 24 stores the request's promise in the entry, and lines 21 and 22 store the answer or the error when it settles.
• In useQuery, line 28 turns the key into a string with JSON.stringify, so ["product", "tea"] from two components gives the same map key. Line 29 reads the entry with useSyncExternalStore, so the component renders again when its entry changes.
• Lines 30 to 35 ask when a component appears without data for its key. The check is an Effect Event, so it reads the latest entry and queryFn while the effect only depends on key.

The key is the most important choice you make. Everything the request depends on goes in it: ["product", id], not ["product"], or the tea and the cake would share one entry, and exercise 2 shows what goes wrong then. TanStack Query's documentation gives the same rule: a key must be unique to the data it names.

One thing this cache gets wrong on purpose: wait 8 seconds, then Hide and Show. The badge still says 9 left. The copy is shown forever, and the server's stock never reaches the page again. The next section fixes that.

Stale data: show the copy, then ask again

A copy that might be old is stale. A good cache does two things with a stale copy: it shows it at once, because an old stock number beats a blank badge, and it asks the server again in the background. The new answer then replaces the copy. This is called stale-while-revalidate (revalidate means "check again"), and SWR takes its name from it. Step 2 of the toy cache adds it:

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9  });10}11 12function ProductTitle() {13  const { data, isPending } = useProduct("tea");14  return <h2>{isPending ? "Loading…" : data.name}</h2>;15}16 17function StockBadge() {18  const { data, isPending, isFetching } = useProduct("tea");19  if (isPending) return <p>Loading…</p>;20  return <p>{data.stock} left {isFetching && "(updating…)"}</p>;21}22 23export default function App() {24  const [open, setOpen] = useState(true);25  return (26    <>27      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>28      <button onClick={() => window.dispatchEvent(new Event("online"))}>Back online</button>29      {open && (30        <>31          <ProductTitle />32          <StockBadge />33        </>34      )}35    </>36  );37}

Wait about 5 seconds, then press Hide and Show. The badge shows 9 left (updating…) at once, and 0.8 seconds later 8 left. In the cache.js tab:

• Line 21 notes when each answer arrived, in updatedAt.
• Line 27 takes a staleTime: how many milliseconds a copy counts as fresh. It's 0 unless you say otherwise, so every copy is stale as soon as it arrives. TanStack Query uses the same default.
• Lines 30 to 33 ask again when there's no copy, or when the copy's age on line 31 has reached staleTime. A request that's already going is still shared, by line 19.
• Line 50 adds isFetching: true whenever a request is going, even with a copy on screen. Line 49's isPending stays true only while there's no copy at all. In App.jsx, line 19 shows Loading… only for isPending, and line 20 adds (updating…) for isFetching.

A copy can also go old while the page just sits there. Libraries ask again at two more moments, and lines 34 to 45 add both. Line 39 listens for visibilitychange, which the browser fires when you switch back to this tab, as TanStack Query does. Line 40 listens for online, which the browser fires when a lost connection comes back. Each time, line 36 checks that the page is visible, and the copy is asked for again if it's stale. Switch to another browser tab for a few seconds and come back: the badge says (updating…). You can't easily drop your connection, so line 28 of App.jsx has a Back online button that fires the same event the browser would.

Asking on every Show can be too much for data that rarely changes. Give the query a staleTime, and a copy is fresh, and used as it is, for that long:

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9    staleTime: 10000,10  });11}12 13function ProductTitle() {14  const { data, isPending } = useProduct("tea");15  return <h2>{isPending ? "Loading…" : data.name}</h2>;16}17 18function StockBadge() {19  const { data, isPending, isFetching } = useProduct("tea");20  if (isPending) return <p>Loading…</p>;21  return <p>{data.stock} left {isFetching && "(updating…)"}</p>;22}23 24export default function App() {25  const [open, setOpen] = useState(true);26  return (27    <>28      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>29      <button onClick={() => window.dispatchEvent(new Event("online"))}>Back online</button>30      {open && (31        <>32          <ProductTitle />33          <StockBadge />34        </>35      )}36    </>37  );38}

Line 9 adds staleTime: 10000. Hide and Show within ten seconds: no request, and no (updating…). After ten seconds, the next Show asks again. Choosing staleTime is choosing how old a copy may be before you care. A product description could be fresh for an hour; stock that changes every few seconds, not at all. The playground lets you watch the cache from the inside while you try each choice.

Pick staleTime: 0, then Show tea: one request, though two components read it. Hide and Show: stale, a new request, and the copy on screen meanwhile. Press Someone buys a tea and then Leave the tab and come back: the new stock arrives. With Infinity, the stock you first saw stays on screen however often you come back.

After a change, mark the copy stale

Reading is half of it. Pages also change server data: add to a cart, like a review, rename a list. A request that changes data is called a mutation. After one, some copies in the cache are wrong, and only your code knows which. Here the cart page saves a tea but tells the cache nothing. The cache.js tab is step 3, which adds three exports at the end.

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { addToCart, fetchCart } from "./api.js";4 5function CartBadge() {6  const { data, isPending, isFetching } = useQuery({ queryKey: ["cart"], queryFn: fetchCart });7  if (isPending) return <p>Cart: loading…</p>;8  return <p>Cart: {data.length} items {isFetching && "(updating…)"}</p>;9}10 11export default function App() {12  const [saving, setSaving] = useState(false);13 14  async function addTea() {15    setSaving(true);16    await addToCart("tea");17    setSaving(false);18  }19 20  return (21    <>22      <CartBadge />23      <button disabled={saving} onClick={addTea}>24        {saving ? "Adding…" : "Add Green tea"}25      </button>26    </>27  );28}

Line 6 reads the cart under the key ["cart"]. addTea on lines 14 to 18 saves a tea on the server (the api.js tab takes 0.7 seconds) and lets the button show Adding… meanwhile. Press Add Green tea: the console says Save: add tea, the server's cart now has one item, and the badge still says Cart: 0 items. The copy in the cache was fresh as far as the cache knew, and nothing told it otherwise.

The fix is to invalidate the copy: mark it stale and ask again. Step 3's invalidateQueries, on lines 63 to 70 of cache.js, does that:

1import { useState } from "react";2import { invalidateQueries, useQuery } from "./cache.js";3import { addToCart, fetchCart } from "./api.js";4 5function CartBadge() {6  const { data, isPending, isFetching } = useQuery({ queryKey: ["cart"], queryFn: fetchCart });7  if (isPending) return <p>Cart: loading…</p>;8  return <p>Cart: {data.length} items {isFetching && "(updating…)"}</p>;9}10 11export default function App() {12  const [saving, setSaving] = useState(false);13 14  async function addTea() {15    setSaving(true);16    await addToCart("tea");17    invalidateQueries(["cart"]);18    setSaving(false);19  }20 21  return (22    <>23      <CartBadge />24      <button disabled={saving} onClick={addTea}>25        {saving ? "Adding…" : "Add Green tea"}26      </button>27    </>28  );29}

Line 17 calls invalidateQueries(["cart"]) once the save is done. Press Add Green tea: the badge says (updating…), the console says Request 2: cart, and then Cart: 1 items. In cache.js, line 64 turns the key into the start of a string, ["cart", so line 66 matches every key that begins with it: ["cart"] and ["cart", "count"], but not ["product", "tea"]. Line 67 marks each match stale, and line 68 asks again with the queryFn that line 24 now keeps in every entry.

That's why keys are arrays that start with the general and end with the specific, like ["product", id]. One call can then cover one product, ["product", "tea"], or every product, ["product"]. The toy asks again for every match, even ones no component shows. TanStack Query only marks those stale, and asks for them when they next appear.

Optimistic updates in the cache

Invalidating waits for two trips to the server, the save and the new copy, before the reader sees their tea. When a change almost always works, you can show it at once instead: an optimistic update. You met the idea in Optimistic UI, with useOptimistic for one component's state. With a cache, you write the expected result into the cache itself, so every component that reads that key shows it.

1import { useState } from "react";2import { getQueryData, invalidateQueries, setQueryData, useQuery } from "./cache.js";3import { addToCart, fetchCart } from "./api.js";4 5function Cart() {6  const { data, isPending } = useQuery({ queryKey: ["cart"], queryFn: fetchCart });7  if (isPending) return <p>Cart: loading…</p>;8  return <p>Cart: {data.length ? data.join(", ") : "empty"}</p>;9}10 11export default function App() {12  const [error, setError] = useState(null);13 14  async function add(id, name) {15    setError(null);16    const before = getQueryData(["cart"]);17    setQueryData(["cart"], (cart = []) => [...cart, name]);18    try {19      await addToCart(id);20    } catch (reason) {21      setQueryData(["cart"], () => before);22      setError(reason.message);23    }24    invalidateQueries(["cart"]);25  }26 27  return (28    <>29      <Cart />30      <button onClick={() => add("tea", "Green tea")}>Add Green tea</button>31      <button onClick={() => add("cake", "Carrot cake")}>Add Carrot cake</button>32      {error && <p>{error}</p>}33    </>34  );35}

Line 16 keeps the copy as it was, with step 3's getQueryData. Line 17 writes the cart with the new item into the cache with setQueryData, so the cart shows it before the server has answered. Line 19 saves. If the server says no, line 21 puts the saved copy back, and line 22 shows why. Either way, line 24 invalidates the cart, so the page ends on what the server really has.

Press Add Green tea: Cart: Green tea at once. Press Add Carrot cake: it shows Green tea, Carrot cake for 0.7 seconds, then the server says Carrot cake is sold out., and the cart is back to Green tea. Here is the same update with TanStack Query's useMutation, as a fragment:

const queryClient = useQueryClient();
const addMutation = useMutation({
  mutationFn: ({ id }) => addToCart(id),
  onMutate: async ({ name }) => {
    await queryClient.cancelQueries({ queryKey: ["cart"] });
    const before = queryClient.getQueryData(["cart"]);
    queryClient.setQueryData(["cart"], (cart = []) => [...cart, name]);
    return { before };
  },
  onError: (error, variables, saved) => {
    queryClient.setQueryData(["cart"], saved.before);
  },
  onSettled: () => queryClient.invalidateQueries({ queryKey: ["cart"] }),
});

Lines 4 to 9 run before the request: line 5 cancels any request for the cart that is still going, so an old answer can't land on top of the new item, which the toy doesn't do. Lines 6 and 7 save the copy and write the new one, and line 8 returns the saved copy. TanStack Query hands it to onError as the third value, and line 11 puts it back. Line 13 invalidates the cart whether the save worked or not.

The same ideas in TanStack Query and SWR

Here is the product page from the overview with the real TanStack Query, version 5.105.0. The result is live: the library loads from a CDN (a server for packages) when the example appears, and the product still comes from the pretend api.js. (Checked on npm in October 2026: TanStack Query 5.105.0 and SWR 2.5.1 were the newest releases of versions 5 and 2. Both work with React 18 and 19.)

1import { useState } from "react";2import { QueryClient, QueryClientProvider, useQuery } from "@tanstack/react-query@5.105.0?dev&deps=react@19.3.1";3import { fetchProduct } from "./api.js";4 5const queryClient = new QueryClient();6 7function useProduct(id) {8  return useQuery({9    queryKey: ["product", id],10    queryFn: () => fetchProduct(id),11  });12}13 14function ProductTitle() {15  const { data, isPending } = useProduct("tea");16  return <h2>{isPending ? "Loading…" : data.name}</h2>;17}18 19function StockBadge() {20  const { data, isPending, isFetching } = useProduct("tea");21  if (isPending) return <p>Loading…</p>;22  return <p>{data.stock} left {isFetching && "(updating…)"}</p>;23}24 25export default function App() {26  const [open, setOpen] = useState(true);27  return (28    <QueryClientProvider client={queryClient}>29      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>30      {open && (31        <>32          <ProductTitle />33          <StockBadge />34        </>35      )}36    </QueryClientProvider>37  );38}

Line 5 makes a QueryClient, the object that holds the cache, and line 28 passes it to every component below with QueryClientProvider, a context provider. Lines 8 to 11 are the same useQuery call as in the toy: a key and a function. Lines 20 to 22 read isPending and isFetching, which mean what they meant in the toy. Run it with the console open: one request for two components. Hide and Show: the copy, (updating…), and a second request, because staleTime is 0 here too.

Line 2 is the one odd line. In your own project you install the package once, and import it by its name:

npm install @tanstack/react-query

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

createRoot(document.getElementById("root")).render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>,
);

Line 1 imports from "@tanstack/react-query", line 3 makes one client for the app, and lines 6 to 8 put the provider around everything, so any component can call useQuery. The live example's import instead names the version and adds ?dev&deps=react@19.3.1. That asks the CDN for the library's development build, built against the same React the result uses. Without it, the library would load a second copy of React, and its hooks would fail with Cannot read properties of null (reading 'useEffect'): React's hooks only work with the one React that is rendering.

And here is the same page with SWR, version 2.5.1:

1import { useState } from "react";2import useSWR from "swr@2.5.1?dev&deps=react@19.3.1";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useSWR(["product", id], () => fetchProduct(id));7}8 9function ProductTitle() {10  const { data, isLoading } = useProduct("tea");11  return <h2>{isLoading ? "Loading…" : data.name}</h2>;12}13 14function StockBadge() {15  const { data, isLoading, isValidating } = useProduct("tea");16  if (isLoading) return <p>Loading…</p>;17  return <p>{data.stock} left {isValidating && "(updating…)"}</p>;18}19 20export default function App() {21  const [open, setOpen] = useState(true);22  return (23    <>24      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>25      {open && (26        <>27          <ProductTitle />28          <StockBadge />29        </>30      )}31    </>32  );33}

Line 6 passes SWR the key and the fetcher as two arguments. SWR needs no provider: it makes its cache for you. It names things a little differently: line 10's isLoading is TanStack Query's isPending, and line 15's isValidating is isFetching. To mark a key stale after a change, SWR uses mutate:

import { useSWRConfig } from "swr";

function AddTeaButton() {
  const { mutate } = useSWRConfig();
  async function addTea() {
    await addToCart("tea");
    mutate(["cart"]); // mark the cart stale and ask again
  }
  return <button onClick={addTea}>Add Green tea</button>;
}

Line 4 gets SWR's mutate from useSWRConfig, and line 7 calls it with the key once the save is done, which marks the cart stale and asks again: what invalidateQueries did in the toy. How to read the table: each row is one idea from this lesson, under its name in the toy, in TanStack Query, and in SWR.

The toy left out most of what makes these libraries worth installing. Both real ones also:

• Retry a failed request before showing the error, waiting longer each time (TanStack Query tries three more times).
• Keep requests in order, help with lists that load page by page, and work with server rendering.
• Work with Suspense: TanStack Query's useSuspenseQuery and SWR's suspense option let a Suspense boundary show the loading state.

TanStack Query also forgets copies nobody has used for five minutes (its gcTime), so its cache doesn't grow forever, and it has developer tools that show the cache.

And sometimes you need neither. A framework such as Next.js or React Router can load a page's data on the server, before the page renders, and refresh it after a form submits. If your framework does that, use its way first, and reach for a library for what's left, like data that changes while the page is open.

A shop cart on TanStack Query

Here is a small shop with the real library: a cart badge, two Add buttons, and the list of what's in the cart. Adding a tea works; adding a cake fails, because it's sold out.

1import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient } from "@tanstack/react-query@5.105.0?dev&deps=react@19.3.1";2import { addToCart, fetchCart } from "./api.js";3 4const queryClient = new QueryClient();5 6function useCart() {7  return useQuery({ queryKey: ["cart"], queryFn: fetchCart });8}9 10function CartBadge() {11  const { data, isPending } = useCart();12  return <p>Cart: {isPending ? "…" : data.length} items</p>;13}14 15function CartList() {16  const { data, isFetching } = useCart();17  if (!data) return null;18  return <p>{data.length ? data.join(", ") : "Nothing yet"} {isFetching && "(updating…)"}</p>;19}20 21function AddButton({ id, name }) {22  const client = useQueryClient();23  const add = useMutation({24    mutationFn: () => addToCart(id),25    onSuccess: () => client.invalidateQueries({ queryKey: ["cart"] }),26  });27  return (28    <p>29      <button disabled={add.isPending} onClick={() => add.mutate()}>30        {add.isPending ? "Adding…" : `Add ${name}`}31      </button>32      {add.isError && ` ${add.error.message}`}33    </p>34  );35}36 37export default function App() {38  return (39    <QueryClientProvider client={queryClient}>40      <CartBadge />41      <AddButton id="tea" name="Green tea" />42      <AddButton id="cake" name="Carrot cake" />43      <CartList />44    </QueryClientProvider>45  );46}

useCart on lines 6 to 8 is a small custom hook around useQuery, so CartBadge (line 11) and CartList (line 16) ask for the cart the same way, with the same key. AddButton uses useMutation on lines 23 to 26: mutationFn is the save, and onSuccess invalidates the cart through the client from useQueryClient on line 22. Line 29 starts the save with add.mutate() and disables the button while add.isPending. Line 32 shows add.error.message when the save fails.

Press Add Green tea. The button says Adding… for the save and the new copy together: when onSuccess returns the promise from invalidateQueries, as it does here, the mutation waits for the cart to arrive. Then the badge and the list both change, though only one request ran. Press Add Carrot cake: Carrot cake is sold out. appears next to its button, and the cart doesn't change.

Common mix-ups

• "A data library replaces useState." No. It holds server state. The open menu, the tab, and the text in a box stay in useState or a reducer.
• "Data from the cache is always up to date." No. It's a copy, often stale. The library shows it and asks again; with a long staleTime, it may not ask for a while.
• "Two components with the same key send two requests." No. They share one entry and one request. Different keys, even for the same data, don't share.
• "The library notices when I change data on the server." No. It can't see your save. Invalidate the keys it affects, or write the new data into the cache.
• "isFetching means there's nothing to show." No. That's isPending (isLoading in SWR). isFetching is also true while a stale copy is on screen.
• "The query key is just a label." No. It decides which components share data, and what invalidating reaches. Put every value the request uses in it.
• "An optimistic update can skip the error case." No. When the server says no, put the saved copy back and show why, then invalidate, or the page shows something the server never saved.

Practice exercises

The exercises use the toy cache, in each one's cache.js tab, so you can read every line that runs. Open the console under each result to see the requests. Run again starts the pretend server and the cache from nothing.

import { useQuery } from "./cache.js";
import { fetchProduct } from "./api.js";

function Price() {
  const { data } = useQuery({ queryKey: ["product", "tea"], queryFn: () => fetchProduct("tea") });
  return <p>Price: {data ? `$${data.price}` : "…"}</p>;
}

function Stock() {
  const { data } = useQuery({ queryKey: ["product", "tea"], queryFn: () => fetchProduct("tea") });
  return <p>Stock: {data ? data.stock : "…"}</p>;
}

export default function App() {
  return (
    <>
      <Price />
      <Stock />
      <Price />
    </>
  );
}

1import { useQuery } from "./cache.js";2import { fetchProduct } from "./api.js";3 4function Price() {5  const { data } = useQuery({ queryKey: ["product", "tea"], queryFn: () => fetchProduct("tea") });6  return <p>Price: {data ? `$${data.price}` : "…"}</p>;7}8 9function Stock() {10  const { data } = useQuery({ queryKey: ["product", "tea"], queryFn: () => fetchProduct("tea") });11  return <p>Stock: {data ? data.stock : "…"}</p>;12}13 14export default function App() {15  return (16    <>17      <Price />18      <Stock />19      <Price />20    </>21  );22}

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function Product({ id }) {6  const { data, isPending } = useQuery({7    queryKey: ["product"],8    queryFn: () => fetchProduct(id),9  });10  return <h2>{isPending ? "Loading…" : data.name}</h2>;11}12 13export default function App() {14  const [id, setId] = useState("tea");15  return (16    <>17      <button onClick={() => setId("tea")}>Tea</button>18      <button onClick={() => setId("cake")}>Cake</button>19      <Product id={id} />20    </>21  );22}

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function Product({ id }) {6  const { data, isPending } = useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9  });10  return <h2>{isPending ? "Loading…" : data.name}</h2>;11}12 13export default function App() {14  const [id, setId] = useState("tea");15  return (16    <>17      <button onClick={() => setId("tea")}>Tea</button>18      <button onClick={() => setId("cake")}>Cake</button>19      <Product id={id} />20    </>21  );22}

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9  });10}11 12function ProductTitle() {13  const { data, isPending } = useProduct("tea");14  return <h2>{isPending ? "Loading…" : data.name}</h2>;15}16 17function StockBadge() {18  const { data, isPending, isFetching } = useProduct("tea");19  if (isPending) return <p>Loading…</p>;20  return <p>{data.stock} left {isFetching && "(updating…)"}</p>;21}22 23export default function App() {24  const [open, setOpen] = useState(true);25  return (26    <>27      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>28      <button onClick={() => window.dispatchEvent(new Event("online"))}>Back online</button>29      {open && (30        <>31          <ProductTitle />32          <StockBadge />33        </>34      )}35    </>36  );37}

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9    staleTime: 10000,10  });11}12 13function ProductTitle() {14  const { data, isPending } = useProduct("tea");15  return <h2>{isPending ? "Loading…" : data.name}</h2>;16}17 18function StockBadge() {19  const { data, isPending, isFetching } = useProduct("tea");20  if (isPending) return <p>Loading…</p>;21  return <p>{data.stock} left {isFetching && "(updating…)"}</p>;22}23 24export default function App() {25  const [open, setOpen] = useState(true);26  return (27    <>28      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>29      <button onClick={() => window.dispatchEvent(new Event("online"))}>Back online</button>30      {open && (31        <>32          <ProductTitle />33          <StockBadge />34        </>35      )}36    </>37  );38}

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9  });10}11 12function ProductTitle() {13  const { data, isPending } = useProduct("tea");14  return <h2>{isPending ? "Loading…" : data.name}</h2>;15}16 17function StockBadge() {18  const { data, isPending, isFetching } = useProduct("tea");19  if (isPending || isFetching) return <p>Loading…</p>;20  return <p>{data.stock} left</p>;21}22 23export default function App() {24  const [open, setOpen] = useState(true);25  return (26    <>27      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>28      {open && (29        <>30          <ProductTitle />31          <StockBadge />32        </>33      )}34    </>35  );36}

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { fetchProduct } from "./api.js";4 5function useProduct(id) {6  return useQuery({7    queryKey: ["product", id],8    queryFn: () => fetchProduct(id),9  });10}11 12function ProductTitle() {13  const { data, isPending } = useProduct("tea");14  return <h2>{isPending ? "Loading…" : data.name}</h2>;15}16 17function StockBadge() {18  const { data, isPending, isFetching } = useProduct("tea");19  if (isPending) return <p>Loading…</p>;20  return <p>{data.stock} left {isFetching && "(updating…)"}</p>;21}22 23export default function App() {24  const [open, setOpen] = useState(true);25  return (26    <>27      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the product</button>28      {open && (29        <>30          <ProductTitle />31          <StockBadge />32        </>33      )}34    </>35  );36}

1import { useState } from "react";2import { useQuery } from "./cache.js";3import { addToCart, fetchCart } from "./api.js";4 5function CartBadge() {6  const { data, isPending, isFetching } = useQuery({ queryKey: ["cart"], queryFn: fetchCart });7  if (isPending) return <p>Cart: loading…</p>;8  return <p>Cart: {data.length} items {isFetching && "(updating…)"}</p>;9}10 11export default function App() {12  const [saving, setSaving] = useState(false);13 14  async function addTea() {15    setSaving(true);16    await addToCart("tea");17    setSaving(false);18  }19 20  return (21    <>22      <CartBadge />23      <button disabled={saving} onClick={addTea}>24        {saving ? "Adding…" : "Add Green tea"}25      </button>26    </>27  );28}

1import { useState } from "react";2import { invalidateQueries, useQuery } from "./cache.js";3import { addToCart, fetchCart } from "./api.js";4 5function CartBadge() {6  const { data, isPending, isFetching } = useQuery({ queryKey: ["cart"], queryFn: fetchCart });7  if (isPending) return <p>Cart: loading…</p>;8  return <p>Cart: {data.length} items {isFetching && "(updating…)"}</p>;9}10 11export default function App() {12  const [saving, setSaving] = useState(false);13 14  async function addTea() {15    setSaving(true);16    await addToCart("tea");17    invalidateQueries(["cart"]);18    setSaving(false);19  }20 21  return (22    <>23      <CartBadge />24      <button disabled={saving} onClick={addTea}>25        {saving ? "Adding…" : "Add Green tea"}26      </button>27    </>28  );29}

1import { useState } from "react";2import { invalidateQueries, useQuery } from "./cache.js";3import { fetchLikes, saveLike } from "./api.js";4 5export default function LikeButton() {6  const { data: likes, isPending } = useQuery({ queryKey: ["likes"], queryFn: fetchLikes });7  const [error, setError] = useState(null);8 9  async function like() {10    setError(null);11    try {12      await saveLike();13    } catch (reason) {14      setError(reason.message);15    }16    invalidateQueries(["likes"]);17  }18 19  if (isPending) return <p>Loading…</p>;20  return (21    <>22      <button onClick={like}>Like ({likes})</button>23      {error && <p>{error}</p>}24    </>25  );26}

1import { useState } from "react";2import { getQueryData, invalidateQueries, setQueryData, useQuery } from "./cache.js";3import { fetchLikes, saveLike } from "./api.js";4 5export default function LikeButton() {6  const { data: likes, isPending } = useQuery({ queryKey: ["likes"], queryFn: fetchLikes });7  const [error, setError] = useState(null);8 9  async function like() {10    setError(null);11    const before = getQueryData(["likes"]);12    setQueryData(["likes"], (count) => count + 1);13    try {14      await saveLike();15    } catch (reason) {16      setQueryData(["likes"], () => before);17      setError(reason.message);18    }19    invalidateQueries(["likes"]);20  }21 22  if (isPending) return <p>Loading…</p>;23  return (24    <>25      <button onClick={like}>Like ({likes})</button>26      {error && <p>{error}</p>}27    </>28  );29}

Check your understanding

For each question, ask what the cache holds under each key, and whether that copy is fresh, stale, or missing.

Key takeaways

• Server state is a copy of data a server holds. It needs loading, sharing, and refreshing; client state stays in useState.
• A data library keeps one cache. The query key names each entry, so components with the same key share one request and one answer.
• A stale copy is shown at once while the library asks again: stale-while-revalidate. staleTime says how long a copy is fresh.
• Libraries also ask again when you come back to the tab and when the connection returns.
• After a change, invalidate the keys it affects. For an instant result, write into the cache first, and put the old copy back if the server says no.
• TanStack Query (useQuery, useMutation, invalidateQueries) and SWR (useSWR, mutate) do all of this, plus retries and more. A framework may load data for you first.

Coming next: Transitions. They let React keep typing and clicking fast while a slow update renders in the background.