Chapter 27: Caching, Offline Support, and Progressive Enhancement

Welcome back, intrepid React developer! In our journey to master modern React, we’ve built robust applications, managed complex states, and ensured our code is clean and testable. But what about making our applications incredibly fast, reliable, and accessible even when the network is flaky or non-existent? That’s exactly what we’ll tackle in this crucial chapter!

Today, we’re diving into the powerful world of caching, enabling offline support, and embracing progressive enhancement. These aren’t just buzzwords; they are essential strategies for building truly resilient and user-friendly web applications that stand out in 2026. By the end of this chapter, you’ll understand how to make your React apps perform like native applications, providing a seamless experience regardless of network conditions.

Before we begin, make sure you’re comfortable with fetching data in React (perhaps using fetch or a library like Axios, as covered in earlier chapters) and have a basic understanding of your frontend build process (like Vite or Webpack). Ready to make your apps unstoppable? Let’s go!

Core Concepts

Imagine your users are on a shaky public Wi-Fi connection, or perhaps commuting through an area with no signal at all. Should your app just break? Absolutely not! Modern web applications leverage powerful browser features to keep things running smoothly.

The Power of Caching

Caching is like having a super-efficient assistant who remembers things for you. Instead of always going back to the source (the server) for every piece of information, your app can store frequently used data or assets locally. This dramatically speeds up load times and reduces network requests.

HTTP Caching: The Browser’s Built-in Helper

The simplest form of caching is handled directly by your browser using HTTP headers. When your React application’s static assets (like your JavaScript bundles, CSS, images) are served, the server can include headers like Cache-Control, ETag, and Last-Modified. These headers tell the browser how long it can store these assets and how to revalidate them.

• Cache-Control: This is your primary directive. It tells the browser whether, how, and for how long it can cache a response. For instance, Cache-Control: public, max-age=31536000 tells the browser that this resource can be cached by any cache for one year.
• ETag (Entity Tag): A unique identifier for a specific version of a resource. If the resource changes, the ETag changes. The browser can send this ETag back to the server to ask, “Hey, do you have a newer version of this resource with this ETag?”
• Last-Modified: Similar to ETag, but based on a timestamp.

While HTTP caching is great for static assets, it’s less effective for dynamic data fetched from APIs, as that data changes frequently and unpredictably.

Client-side Data Caching: Smartly Managing Dynamic Data

For dynamic data, we turn to client-side caching libraries. These libraries handle the complexities of fetching, storing, and invalidating data right in your React application. The undisputed champions in this arena as of early 2026 are TanStack Query (v5) and SWR.

How do they work? They often follow patterns like “stale-while-revalidate”:

1. When you request data, the library first returns any immediately available stale data from its cache.
2. In the background, it fetches the fresh data from the network.
3. Once the fresh data arrives, it updates the UI and the cache.

This gives users an instant response with potentially slightly old data, then seamlessly updates to the latest. It’s a fantastic user experience!

Why use a library like TanStack Query (v5)?

• Automatic Caching: Fetched data is automatically cached.
• Background Refetching: Data can be refetched in the background when the window regains focus, on an interval, or when a mutation occurs.
• Stale-While-Revalidate: Provides instant UI feedback while fetching fresh data.
• Query Invalidation: Easily invalidate cached data when mutations occur (e.g., after a POST or PUT request).
• Error Handling & Retries: Built-in mechanisms for handling network errors and retrying failed requests.
• Optimistic Updates: Allows you to update the UI before a server response, making the app feel incredibly fast.

Offline Support with Service Workers

Now, let’s talk about true offline capabilities. What if there’s no network connection at all? This is where Service Workers shine!

A Service Worker is a JavaScript file that your browser runs in the background, separate from your main React application. It acts like a programmable proxy between your browser and the network.

What can Service Workers do?

• Intercept Network Requests: They can catch all network requests made by your application and decide whether to serve them from the network, from a cache, or even generate a response programmatically.
• Cache Assets: They can proactively cache assets (HTML, CSS, JS, images, API responses) so your app works offline.
• Push Notifications: Enable push notifications even when your app isn’t open.
• Background Sync: Defer actions until the user has a stable network connection.

The Service Worker Lifecycle

Understanding the lifecycle is key to using Service Workers effectively:

Figure 27.1: Simplified Service Worker Lifecycle

1. Registration: Your main application JavaScript tells the browser to register a Service Worker.
2. Installation: The browser downloads the Service Worker script. If successful, it fires an install event. This is where you typically cache static assets that your app needs to function offline (e.g., your React bundle, core CSS).
3. Activation: After installation, the activate event fires. This is a good place to clean up old caches from previous Service Worker versions.
4. Active: Once activated, the Service Worker can now intercept network requests.

Workbox: The Easier Way to Manage Service Workers

While you can write Service Workers from scratch, it’s often complex and error-prone. This is where Workbox comes in. Workbox is a set of JavaScript libraries from Google that makes it much easier to manage Service Workers and implement common caching strategies. As of early 2026, Workbox v7 is the stable and recommended version.

Workbox helps you:

• Precache assets during installation.
• Define runtime caching strategies for various types of requests (e.g., CacheFirst, NetworkFirst, StaleWhileRevalidate).
• Handle routing for different URL patterns.
• Simplify Service Worker updates.

Progressive Web Apps (PWAs): App-like Experiences

Offline support and caching are foundational for Progressive Web Apps (PWAs). A PWA is a web application that uses modern web capabilities to deliver an app-like experience to users. They are:

• Reliable: Load instantly and never show the “downasaur” (thanks to Service Workers).
• Fast: Respond quickly to user interactions with smooth animations (thanks to caching).
• Engaging: Feel like a natural app on the device, with features like push notifications and home screen installation.

The two core ingredients for a PWA are:

1. Service Workers: For offline functionality and caching.
2. Web App Manifest (manifest.json): A JSON file that tells the browser how your PWA should look and behave when installed on a user’s device. It includes things like:
   • name and short_name
   • start_url
   • display mode (e.g., standalone for a full app experience)
   • icons for different device resolutions
   • theme_color and background_color

Progressive Enhancement: Baseline First

Finally, let’s talk about Progressive Enhancement. This is a philosophy for web development that states you should build web experiences that deliver a baseline of content and functionality to all users, then add more advanced features and experiences for those with modern browsers, good network conditions, and JavaScript enabled.

In the context of React, this means:

• Core Content First: Ensure the most critical content of your page is accessible even if JavaScript fails to load or runs slowly. This often involves Server-Side Rendering (SSR) or Static Site Generation (SSG) to deliver pre-rendered HTML (topics we touched upon in earlier chapters on Next.js or Remix).
• Layered Enhancements: Your React application then “hydrates” this basic HTML, adding interactivity, dynamic updates, and rich UI features. If JavaScript isn’t available, the user still gets a usable, albeit less interactive, experience.

This approach ensures your application is robust, accessible, and provides a good user experience to the widest possible audience, regardless of their device or network.

Step-by-Step Implementation: Building a PWA with Caching

Let’s put these concepts into practice! We’ll start with a fresh React project and equip it with PWA capabilities using Workbox and a Web App Manifest. We’ll then integrate client-side data caching with TanStack Query.

Prerequisites: Ensure you have Node.js (v18.x or higher, current stable recommended as of 2026-01-31) and npm/yarn installed.

Step 1: Create a New React Project with Vite

Vite is a fantastic build tool that makes setting up React projects a breeze and often comes with PWA integration plugins.

Open your terminal and run:

npm create vite@latest my-pwa-app -- --template react-ts
cd my-pwa-app
npm install
npm run dev

This will create a new React project with TypeScript. You should see a basic React app running at http://localhost:5173 (or similar).

Step 2: Add a Web App Manifest

First, let’s create our manifest.json file. This tells the browser about our PWA.

Create a new file public/manifest.json:

{
  "name": "My Awesome PWA App",
  "short_name": "PWA App",
  "description": "A progressive web application built with React.",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#007bff",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Explanation:

• name and short_name: Displayed to the user (e.g., on the home screen).
• description: What your app does.
• start_url: The URL to load when the app is launched. / means the root of your application.
• display: standalone makes the app open without browser UI (like a native app). Other options include fullscreen, minimal-ui, browser.
• background_color, theme_color: Used for splash screens and browser UI.
• icons: An array of icon objects for different resolutions. You’ll need to create these images and place them in public/icons/. For now, you can use placeholder images or generate them later.

Next, link this manifest in your index.html file. Open index.html (in the root of your project, not src/) and add the following line inside the <head> section:

<!-- public/index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + React + TS</title>
    <!-- Add this line for the PWA manifest -->
    <link rel="manifest" href="/manifest.json" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Explanation:

• We’re linking the manifest.json file. The browser will automatically parse this and enable PWA features like “Add to Home Screen” if the criteria are met (which include having a Service Worker, which we’ll add next!).

Step 3: Implement Service Worker with vite-plugin-pwa

For Vite projects, vite-plugin-pwa is the easiest way to integrate Workbox and manage your Service Worker.

Install the plugin:

npm install -D vite-plugin-pwa@^0.17.0

(As of late 2025/early 2026, vite-plugin-pwa version 0.17.x is stable and compatible with Vite v5.)

Now, configure your vite.config.ts file to use the plugin.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { VitePWA } from 'vite-plugin-pwa'; // Import VitePWA

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    VitePWA({ // Add VitePWA plugin configuration
      registerType: 'autoUpdate', // Automatically update Service Worker
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg,webp,json}'], // Cache these file types
        runtimeCaching: [ // Define runtime caching strategies for dynamic content
          {
            urlPattern: ({ url }) => url.origin === self.location.origin && url.pathname.startsWith('/api/'),
            handler: 'NetworkFirst', // Try network first, then fall back to cache
            options: {
              cacheName: 'api-cache',
              expiration: {
                maxEntries: 10,
                maxAgeSeconds: 60 * 60 * 24 * 7, // 7 days
              },
              cacheableResponse: {
                statuses: [0, 200],
              },
            },
          },
        ],
      },
      manifest: { // This generates your manifest.json for you, or merges with existing
        name: 'My Awesome PWA App',
        short_name: 'PWA App',
        description: 'A progressive web application built with React.',
        theme_color: '#007bff',
        icons: [
          {
            src: 'icons/icon-192x192.png',
            sizes: '192x192',
            type: 'image/png',
          },
          {
            src: 'icons/icon-512x512.png',
            sizes: '512x512',
            type: 'image/png',
          },
          {
            src: 'icons/icon-512x512.png',
            sizes: '512x512',
            type: 'image/png',
            purpose: 'maskable',
          },
        ],
      },
    }),
  ],
});

Explanation:

• We import VitePWA and add it to our plugins array.
• registerType: 'autoUpdate' tells the plugin to automatically register and update the Service Worker.
• workbox configuration:
  • globPatterns: These are files that Workbox will precache during the Service Worker installation phase. These are typically your static assets that are part of your build.
  • runtimeCaching: This is where you define strategies for dynamic content (like API calls) that are fetched after your app has loaded. We’ve added a NetworkFirst strategy for any GET requests to /api/ endpoints.
    • NetworkFirst: Tries to fetch from the network first. If successful, it caches the response and returns it. If the network fails, it falls back to the cache. This is great for data that should ideally be fresh, but can tolerate being stale if offline.
• manifest: You can define your manifest directly here, and the plugin will generate manifest.json for you. If you already have one in public/, it will merge.

Now, you need to add the Service Worker registration code to your main.tsx (or main.jsx).

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';

// Import and register the PWA service worker
import { registerSW } from 'virtual:pwa-register';

// Register the Service Worker
// This will typically only run in production builds or when the build tool is configured for PWA
registerSW({ immediate: true });

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Explanation:

• virtual:pwa-register is a virtual module provided by vite-plugin-pwa that handles Service Worker registration.
• registerSW({ immediate: true }) tells the browser to register the Service Worker immediately.

To test this, you’ll need to build your application for production:

npm run build
npm run preview

Then open your browser to the preview URL (e.g., http://localhost:4173). Open DevTools (F12) and go to the “Application” tab. You should see “Service Workers” listed on the left, and your new Service Worker should be active! You can also check “Manifest” to see your manifest.json being parsed.

Try toggling “Offline” in the Network tab. Your app should still load!

Step 4: Implement Client-side Data Caching with TanStack Query (v5)

Now, let’s add robust data caching for our dynamic API calls.

Install TanStack Query:

npm install @tanstack/react-query@^5.0.0

(As of early 2026, @tanstack/react-query version 5.x.x is the stable release.)

First, wrap your App component with QueryClientProvider in main.tsx.

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import { registerSW } from 'virtual:pwa-register';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; // Import QueryClient and Provider

// Register the Service Worker
registerSW({ immediate: true });

// Create a client
const queryClient = new QueryClient(); // Initialize QueryClient

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}> {/* Wrap App with QueryClientProvider */}
      <App />
    </QueryClientProvider>
  </React.StrictMode>,
);

Explanation:

• QueryClient is the core instance that manages all your queries, caches, and mutations.
• QueryClientProvider makes the queryClient available to all components within its tree.

Now, let’s create a simple component that fetches and caches data. Imagine we have a mock API at /api/data.

Modify src/App.tsx:

// src/App.tsx
import { useState } from 'react';
import reactLogo from './assets/react.svg';
import viteLogo from '/vite.svg';
import './App.css';
import { useQuery } from '@tanstack/react-query'; // Import useQuery

// Mock API fetch function
// In a real app, this would be an actual API call
const fetchData = async () => {
  console.log('Fetching data from API...');
  const response = await fetch('/api/data'); // Simulate an API endpoint
  if (!response.ok) {
    throw new Error('Network response was not ok');
  }
  return response.json();
};

function App() {
  const [count, setCount] = useState(0);

  // Use TanStack Query to fetch and cache data
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ['myData'], // Unique key for this query
    queryFn: fetchData,   // The async function to fetch data
    staleTime: 5 * 1000,  // Data is considered fresh for 5 seconds
    gcTime: 60 * 1000,    // Cached data is garbage collected after 1 minute if unused
  });

  if (isLoading) return <div>Loading data...</div>;
  if (isError) return <div>Error: {error?.message}</div>;

  return (
    <>
      <div>
        <a href="https://vitejs.dev" target="_blank">
          <img src={viteLogo} className="logo" alt="Vite logo" />
        </a>
        <a href="https://react.dev" target="_blank">
          <img src={reactLogo} className="logo react" alt="React logo" />
        </a>
      </div>
      <h1>Vite + React</h1>
      <div className="card">
        <button onClick={() => setCount((count) => count + 1)}>
          count is {count}
        </button>
        <p>
          Edit <code>src/App.tsx</code> and save to test HMR
        </p>
      </div>
      <p className="read-the-docs">
        Click on the Vite and React logos to learn more
      </p>

      {/* Display fetched data */}
      <h2>Fetched Data:</h2>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </>
  );
}

export default App;

Explanation:

• We import useQuery from @tanstack/react-query.
• fetchData is an async function that simulates fetching data. For our example, we’ll need to mock /api/data.
• useQuery takes an object with:
  • queryKey: A unique array used to identify and cache this query’s data.
  • queryFn: The asynchronous function that fetches the data.
  • staleTime: How long the data is considered “fresh”. After this time, it becomes “stale” but is still served from the cache while a background refetch occurs.
  • gcTime: How long unused cached data remains in memory before being garbage collected.
• We display isLoading, isError, and the data itself.

To make the /api/data endpoint work for development, we can use Vite’s proxy capabilities. Add this to your vite.config.ts:

// vite.config.ts (excerpt)
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    react(),
    VitePWA({ /* ...pwa config... */ }),
  ],
  server: { // Add this server configuration
    proxy: {
      '/api': {
        target: 'http://localhost:3001', // Or any mock server URL
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
});

Explanation:

• This tells Vite to redirect any requests starting with /api to http://localhost:3001.
• You’ll need a simple mock server running on http://localhost:3001. Create a server.js file in your project root:

// server.js
import express from 'express';
import cors from 'cors';

const app = express();
const port = 3001;

app.use(cors()); // Enable CORS for development

app.get('/data', (req, res) => {
  console.log('Serving /data from mock server');
  res.json({
    message: `Hello from the mock API! Data fetched at ${new Date().toLocaleTimeString()}`,
    items: [
      { id: 1, name: 'Item A' },
      { id: 2, name: 'Item B' },
      { id: 3, name: 'Item C' },
    ],
  });
});

app.get('/static-data', (req, res) => {
  console.log('Serving /static-data from mock server');
  res.json({
    staticMessage: `This is static data, fetched at ${new Date().toLocaleTimeString()}`,
    version: '1.0',
  });
});

app.get('/dynamic-data', (req, res) => {
  console.log('Serving /dynamic-data from mock server');
  res.json({
    dynamicMessage: `This is dynamic data, fetched at ${new Date().toLocaleTimeString()}`,
    random: Math.random(),
  });
});

app.listen(port, () => {
  console.log(`Mock API server listening at http://localhost:${port}`);
});

Install express and cors for the mock server:

npm install express@^4.18.2 cors@^2.8.5

Run the mock server in a separate terminal:

node server.js

Now, run your React app in development mode:

npm run dev

You should see the “Fetched Data” section update immediately, and subsequent fetches within the staleTime will be instant. After staleTime passes, you’ll briefly see the old data, then a background fetch will update it. Observe the network tab!

Mini-Challenge: Enhance Service Worker API Caching

You’ve got the basics down! Now, let’s refine our Service Worker’s API caching strategy.

Challenge: Modify the vite-plugin-pwa configuration in vite.config.ts to implement a CacheFirst strategy for API calls to /api/static-data, while keeping NetworkFirst for /api/dynamic-data.

Hint: You can add multiple runtimeCaching entries. The order matters! Workbox will use the first matching urlPattern.

What to Observe/Learn:

1. After making the changes, rebuild (npm run build) and preview (npm run preview).
2. Open your browser’s DevTools, go to the “Application” tab, then “Service Workers”. Ensure your Service Worker is active.
3. Go to the “Network” tab.
4. Modify your App.tsx to call both /api/static-data and /api/dynamic-data using useQuery (remember to use different queryKeys!).
5. Load your app.
6. Go offline (in DevTools Network tab).
7. Reload the page.
8. Observe how /api/static-data is served instantly from the cache (even if offline) and /api/dynamic-data fails if offline (because NetworkFirst requires a network connection to try first, then falls back to cache if available, but if it wasn’t cached before going offline, it will fail). If you were online, NetworkFirst would still try the network first.

This exercise helps you understand how to fine-tune caching strategies for different types of API data, optimizing for both freshness and offline availability.

Common Pitfalls & Troubleshooting

1. Service Worker Not Updating: This is a classic! Browsers are aggressive about caching Service Workers.

   • Symptom: You update your vite.config.ts or Service Worker code, but the changes don’t appear in the browser.
   • Solution: In Chrome DevTools (Application tab -> Service Workers), check “Update on reload” and click “skipWaiting”. For production, vite-plugin-pwa’s registerType: 'autoUpdate' helps, but sometimes users might need a hard refresh (Ctrl+Shift+R or Cmd+Shift+R).
   • Explanation: A Service Worker controls network requests, so it can’t simply replace itself without potentially breaking ongoing requests. It typically waits until all tabs controlled by the old Service Worker are closed before activating the new one. skipWaiting() forces activation immediately.

2. Caching Stale Data (When You Don’t Want To):

   • Symptom: Your app shows old data even when you expect new data.
   • Solution:
     • For static assets: Ensure Cache-Control headers are appropriate (e.g., no-cache for HTML, shorter max-age for frequently updated JS/CSS if not using versioned filenames).
     • For dynamic data with TanStack Query: Adjust staleTime to a shorter duration, or use queryClient.invalidateQueries(['yourQueryKey']) after a mutation to force a refetch.
     • For Service Worker runtime caching: Choose the right strategy (NetworkFirst for fresher data, CacheFirst for truly static API responses), and set maxAgeSeconds carefully.

3. Debugging Service Workers:

   • Symptom: Service Worker isn’t intercepting requests, or caching isn’t working as expected.
   • Solution: Use the “Application” tab in DevTools.
     • Service Workers: See the status, unregister, update, or debug the Service Worker script itself.
     • Cache Storage: Inspect what’s actually in your Service Worker caches.
     • Network Tab: Observe requests. Look for (from ServiceWorker) or (from disk cache) indicators.
   • Pro-Tip: Service Workers run in a separate thread. console.log statements inside your Service Worker code will appear in a dedicated Service Worker console, not your main app console.

Summary

Phew! You’ve just unlocked some incredibly powerful techniques for building modern web applications. Let’s recap what we’ve covered:

• Caching: We explored HTTP caching for static assets and dove deep into client-side data caching using libraries like TanStack Query (v5), which provides intelligent stale-while-revalidate strategies for dynamic data.
• Offline Support: You learned about Service Workers – powerful background scripts that act as network proxies, enabling your application to intercept requests and serve content from a cache, making your app accessible even without a network connection.
• Workbox: We saw how Workbox (v7) simplifies Service Worker development by providing robust tools and common caching strategies, especially when integrated with build tools like Vite using vite-plugin-pwa.
• Progressive Web Apps (PWAs): We understood how Service Workers, combined with a Web App Manifest, transform your React application into an installable, app-like experience on users’ devices.
• Progressive Enhancement: This philosophy ensures your application provides a baseline experience for all users, then layers on advanced features, making your app resilient and universally accessible.

By mastering these concepts, you’re not just building React apps; you’re crafting high-performance, resilient, and delightful user experiences that adapt to any network condition. This is a hallmark of truly production-ready applications in 2026.

In the next chapter, we’ll shift our focus to even broader production-grade topics like project structure, scalable architecture, and ensuring your application is ready for the long haul!

References

1. React Official Documentation: https://react.dev/
2. TanStack Query Documentation (v5): https://tanstack.com/query/latest
3. Workbox Documentation (v7): https://developer.chrome.com/docs/workbox/
4. MDN Web Docs - Service Workers: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API
5. MDN Web Docs - Progressive Web Apps: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps
6. Vite Plugin PWA Documentation: https://vite-pwa-org.netlify.app/

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.