JavaScript and React course ยท Module 11: Data Fetching and APIs

Data Caching and Stale-While-Revalidate

8 min read ยท
In this lesson8

Imagine your spaceship repeatedly asking Mission Control for the same planetary data. Each time you wait for a response, even if the data hasn't changed. What a waste! The solution is caching: storing data locally in a cache and refreshing it in the background.

Why is Caching Important?

Let's compare two decks of the same ship.

Without cache:

  • Every navigation = new request = spinner
  • The user sees "Loading..." even for data they've already seen
  • Unnecessary load on the server and network

With cache:

  • Data displayed instantly from memory
  • Background refresh (no spinner)
  • Better user experience

A cache has a price, though: the data in memory may be outdated. The whole art is knowing when to trust it and when to ask again.

The Stale-While-Revalidate (SWR) Pattern

SWR is a caching strategy known from HTTP (the stale-while-revalidate directive of the Cache-Control header) and used by libraries such as SWR and TanStack Query. The name says it all:

  1. Stale: immediately show data from the cache (even if it may be outdated)
  2. While-Revalidate: at the same time, fetch fresh data from the server in the background
  3. When the fresh data arrives, update the view

The same flow written out as steps looks like this:

// SWR Visualization:
// Step 1: User enters the page
//   -> Cache exists? YES -> Show cached data (instantly!)
//   -> Simultaneously: send request to server

// Step 2: Server responds
//   -> Data changed? YES -> Update view and cache
//   -> Data the same? -> Do nothing

// Step 3: User returns to the page
//   -> Repeat from Step 1 (instant display!)

The user doesn't wait on the first return or on any later one, and the server still gets asked. So SWR doesn't save requests, it saves waiting time.

Simple Cache with Map

The simplest cache can be built with a Map object, a key-value dictionary. The key will be the URL, and the value the data together with a timestamp. The map lives outside the component, so it survives unmounting. Here's a custom hook that uses it:

// Global cache - lives outside components
const cache = new Map();

function useFetchWithCache(url, ttl = 60000) {
  const [data, setData] = useState(() => {
    const cached = cache.get(url);
    if (cached && Date.now() - cached.timestamp < ttl) {
      return cached.data; // Instant data from cache!
    }
    return null;
  });
  const [loading, setLoading] = useState(!cache.has(url));
  const [error, setError] = useState(null);

  useEffect(() => {
    const controller = new AbortController();

    async function fetchData() {
      try {
        // If we have cache - don't show spinner
        if (!cache.has(url)) setLoading(true);
        setError(null);

        const response = await fetch(url, {
          signal: controller.signal,
        });
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}`);
        }
        const result = await response.json();

        // Save to cache with timestamp
        cache.set(url, {
          data: result,
          timestamp: Date.now(),
        });
        setData(result);
      } catch (err) {
        if (err.name !== 'AbortError') {
          setError(err.message);
        }
      } finally {
        setLoading(false);
      }
    }

    fetchData();
    return () => controller.abort();
  }, [url, ttl]);

  return { data, loading, error };
}

The function passed to useState (lazy initialization) runs only on the first render and pulls the data out of the cache right away. The effect still always asks the server, and that is exactly the "revalidate" part. Everything else, AbortController, response.ok and the states, comes straight from the previous lessons.

TTL (Time To Live) - Cache Lifetime

TTL defines how long data in the cache is considered current. In our hook it decides whether to show the data from memory immediately on mount. The fresh background request always departs anyway:

// TTL = 60000ms (1 minute)
// Data older than 1 minute will be fetched again

// Short TTL (5-30s) - frequently changing data
// e.g. cryptocurrency prices, mission status
const liveData = useFetchWithCache('/api/status', 5000);

// Medium TTL (1-5 min) - moderately changing data
// e.g. planet list, ship catalog
const catalog = useFetchWithCache('/api/planets', 60000);

// Long TTL (10-60 min) - rarely changing data
// e.g. configuration, static lists
const config = useFetchWithCache('/api/config', 600000);

Choosing a TTL is a business decision, not a technical one. Ask yourself how much it would hurt the user to see data that is a minute old.

Cache Invalidation - Forcing a Refresh

Sometimes we know for sure that the cached data is outdated, for example right after adding a new mission. Then we remove the entry by hand, which is called invalidating the cache:

// Simple invalidation - remove from cache
function invalidateCache(url) {
  cache.delete(url);
}

// After adding a new mission - invalidate the mission list
async function createMission(data) {
  await fetch('/api/missions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  // Force refresh of mission list
  invalidateCache('/api/missions');
}

The rule is simple: every mutation (POST, PUT, DELETE) that changes data on the server should invalidate the cache for that data.

Optimistic Updates - Updating Before the Response

Instead of waiting for the server, we can update the UI immediately and undo the change only if the server refuses. The key is remembering the previous state so we have something to go back to:

function MissionList() {
  const [missions, setMissions] = useState([]);

  const deleteMission = async (id) => {
    // 1. OPTIMISTICALLY remove from UI (instantly!)
    const previousMissions = [...missions];
    setMissions(prev => prev.filter(m => m.id !== id));

    try {
      // 2. Send DELETE request to server
      const response = await fetch(`/api/missions/${id}`, {
        method: 'DELETE',
      });
      // fetch doesn't throw for 4xx/5xx - check it ourselves
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      // Success - UI already updated!
    } catch (error) {
      // 3. ERROR - restore previous state (rollback)
      setMissions(previousMissions);
      alert('Failed to delete mission');
    }
  };

  return (
    <ul>
      {missions.map(m => (
        <li key={m.id}>
          {m.name}
          <button onClick={() => deleteMission(m.id)}>
            Delete
          </button>
        </li>
      ))}
    </ul>
  );
}

The response.ok check is essential here: without it, a 500 response would never reach catch and the rollback would never run. I recommend optimistic updates for operations that almost always succeed, like a like or removing an item from a list.

TanStack Query -- Professional Caching

In large projects, instead of writing your own cache, we use the TanStack Query library (formerly React Query, currently version 5). It's like an advanced onboard computer that automatically manages all communication. We wrap the app in QueryClientProvider and fetch data with the useQuery hook:

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

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <PlanetList />
    </QueryClientProvider>
  );
}

function PlanetList() {
  // useQuery - automatic cache, SWR, retry, refetch
  const { data, isLoading, error } = useQuery({
    queryKey: ['planets'],
    queryFn: () =>
      fetch('https://swapi.dev/api/planets/')
        .then(res => res.json()),
    staleTime: 60000, // Data fresh for 1 minute
    gcTime: 300000, // Remove from cache after 5 minutes
  });

  if (isLoading) return <p>Scanning the galaxy...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data.results.map(planet => (
        <li key={planet.name}>{planet.name}</li>
      ))}
    </ul>
  );
}

There isn't a single useState or useEffect here: the library provides the loading and error states and the cache. One caveat from the docs: queryFn has to throw for the query to end up in the error state, and fetch() doesn't throw for 4xx/5xx. In production, add a res.ok check.

TanStack Query - Key Concepts

Below are the most important options in one place. queryKey identifies the data in the cache, staleTime says how long it stays fresh, and gcTime (called cacheTime in version 4) when unused data gets removed:

// 1. queryKey - unique identifier for data in cache
//    Key change = new request
const planets = useQuery({
  queryKey: ['planets', page],
  queryFn: () => fetchPlanets(page),
});

// 2. staleTime - how long data is fresh
//    staleTime: 0 - always refresh (default)
//    staleTime: 60000 - fresh for 1 minute
//    staleTime: Infinity - never refresh

// 3. gcTime (garbage collection) - when to remove from cache
//    gcTime: 300000 - remove after 5 min of inactivity

// 4. Automatic refetch:
//    - When window regains focus
//    - When network reconnects
//    - At regular intervals (refetchInterval)

// 5. useMutation - write operations with invalidation
const mutation = useMutation({
  mutationFn: (newMission) =>
    fetch('/api/missions', {
      method: 'POST',
      body: JSON.stringify(newMission),
    }),
  onSuccess: () => {
    // After adding a mission - invalidate mission list cache
    queryClient.invalidateQueries({
      queryKey: ['missions']
    });
  },
});

The default staleTime is 0 and the default gcTime is 5 minutes. staleTime: Infinity only turns off automatic refreshing, manual invalidation still works. Inside a component you get the client with const queryClient = useQueryClient(), and in a real POST add the Content-Type header from the previous lesson. Notice that invalidateQueries is exactly our manual invalidation, just done for you.

Remember: the cache is the onboard computer's memory, it shows what you already know and checks in the background whether the galaxy has changed.

Code for this lesson: App.jsx
import React, { useState, useEffect } from 'react';

// Global cache with Map
const cache = new Map();
let fetchCount = 0;

function useFetchWithCache(url, ttl = 30000) {
  const [data, setData] = useState(() => {
    const cached = cache.get(url);
    if (cached && Date.now() - cached.timestamp < ttl) {
      return cached.data;
    }
    return null;
  });
  const [loading, setLoading] = useState(!cache.has(url));
  const [error, setError] = useState(null);
  const [source, setSource] = useState('');

  useEffect(() => {
    const controller = new AbortController();

    // Check cache
    const cached = cache.get(url);
    if (cached && Date.now() - cached.timestamp < ttl) {
      setData(cached.data);
      setSource('cache (TTL: ' + Math.round((ttl - (Date.now() - cached.timestamp)) / 1000) + 's left)');
      setLoading(false);
      // SWR: fetch in the background despite the cache
    }

    async function fetchData() {
      try {
        if (!cached) setLoading(true);
        setError(null);
        fetchCount++;
        const currentFetch = fetchCount;

        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        const result = await response.json();

        cache.set(url, { data: result, timestamp: Date.now() });
        setData(result);
        setSource('server (fetch #' + currentFetch + ')');
      } catch (err) {
        if (err.name !== 'AbortError') setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    fetchData();
    return () => controller.abort();
  }, [url, ttl]);

  const invalidate = () => {
    cache.delete(url);
    setSource('cache invalidated - refetching...');
    setData(null);
    setLoading(true);
  };

  return { data, loading, error, source, invalidate };
}

function PlanetPanel() {
  const { data, loading, error, source, invalidate } = useFetchWithCache(
    'https://swapi.dev/api/planets/', 30000
  );

  return (
    <div className="panel">
      <h3>Planets</h3>
      <div className="source-badge">{source || 'loading...'}</div>
      <button className="btn" onClick={invalidate}>Invalidate cache</button>
      {loading && <div className="mini-loading"><div className="spinner"></div></div>}
      {error && <p className="error-text">{error}</p>}
      {data && data.results.slice(0, 5).map(p => (
        <div key={p.name} className="item">{p.name} - {p.climate}</div>
      ))}
    </div>
  );
}

function PeoplePanel() {
  const { data, loading, error, source, invalidate } = useFetchWithCache(
    'https://swapi.dev/api/people/', 30000
  );

  return (
    <div className="panel">
      <h3>Characters</h3>
      <div className="source-badge">{source || 'loading...'}</div>
      <button className="btn" onClick={invalidate}>Invalidate cache</button>
      {loading && <div className="mini-loading"><div className="spinner"></div></div>}
      {error && <p className="error-text">{error}</p>}
      {data && data.results.slice(0, 5).map(p => (
        <div key={p.name} className="item">{p.name} - {p.birth_year}</div>
      ))}
    </div>
  );
}

function CacheStatus() {
  const [, forceUpdate] = useState(0);
  useEffect(() => {
    const interval = setInterval(() => forceUpdate(n => n + 1), 1000);
    return () => clearInterval(interval);
  }, []);

  return (
    <div className="cache-status">
      <h3>Cache State (Map)</h3>
      <p>Entries: {cache.size}</p>
      {Array.from(cache.entries()).map(([key, val]) => (
        <div key={key} className="cache-entry">
          <span className="cache-key">{key.replace('https://swapi.dev/api/', '/')}</span>
          <span className="cache-age">{Math.round((Date.now() - val.timestamp) / 1000)}s ago</span>
        </div>
      ))}
      <button className="btn danger" onClick={() => { cache.clear(); forceUpdate(n => n + 1); }}>Clear entire cache</button>
    </div>
  );
}

function App() {
  const [showPanels, setShowPanels] = useState(true);

  return (
    <div className="dashboard">
      <h1>Cache & SWR Demo</h1>
      <p>Unmount the panels and mount them again - data appears instantly from cache!</p>
      <button className="btn toggle" onClick={() => setShowPanels(!showPanels)}>
        {showPanels ? 'Unmount panels' : 'Mount panels (data from cache!)'}
      </button>
      {showPanels && (
        <div className="grid">
          <PlanetPanel />
          <PeoplePanel />
        </div>
      )}
      <CacheStatus />
    </div>
  );
}

export default App;

Docs entries used in this lesson

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. What does the name of the 'Stale-While-Revalidate' (SWR) pattern mean?

  2. 2. When should you 'invalidate' (delete/refresh) the cache in a React application?

Hands-on tasks in the game

  • Vertical ordering

    Arrange the steps of the Stale-While-Revalidate pattern in order:

  • Code editor

    Cache implementation with TTL

  • Code editor

    Optimistic updates with rollback

  • Click in order

    Click the elements in order to configure useQuery with TanStack Query:

  1. Put in orderSWR Pattern Lifecycle
  2. QuestionStale-While-Revalidate Pattern
  3. Coding taskPractice: Cache with Map and TTL
  4. Coding taskPractice: Optimistic Updates
  5. QuestionCache Invalidation
  6. Click in orderConfiguring useQuery in TanStack Query

Useful articles