Building PWAs: Offline-First Like a Jedi Master

#webdev #react #node #frontend

The Quest Begins (The "Why")

I still remember the first time I tried to show a friend a progressive web app on a spotty café Wi‑Fi. The page loaded, the spinner spun, and then—nothing. My friend shrugged, pulled out their phone, and opened the native version of the same service. I felt like I’d shown up to a lightsaber duel with a butter knife.

That moment lit a fire under me. Why should users lose access to our carefully crafted UI just because the network decides to take a nap? I wanted a way for the app to keep working, to feel reliable, even when the connection drops. In other words, I wanted an offline‑first experience—something that didn’t just gracefully degrade, but actually thrived when the network vanished.

If you’ve ever felt the frustration of a blank screen while waiting for a request to time out, you know exactly what dragon we’re slaying today.

The Revelation (The Insight)

The secret weapon? Service workers combined with a thoughtful caching strategy. Think of a service worker as a tiny, trusty sidekick that intercepts every network request, decides whether to serve a cached copy or go to the server, and can even push updates in the background. When you pair that with a web app manifest (so the browser knows it’s installable) and a few clever cache‑first rules, you get an app that works offline by default—not as an afterthought.

The magic clicked for me when I realized offline‑first isn’t about “detecting when you’re offline and then showing a fallback page.” It’s about designing the app to assume the network is unreliable from the start, then letting the service worker fill in the gaps. It’s a mindset shift, and once you adopt it, everything else feels like a natural extension.

Wielding the Power (Code & Examples)

Let’s go from a fragile, network‑dependent page to a resilient PWA. I’ll show the “before” (the struggle) and the “after” (the victory).

Before: Plain fetch, no safety net

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Notes App</title>
  <link rel="stylesheet" href="/styles.css">
</head>
<body>
  <h1>My Notes</h1>
  <ul id="notes-list"></ul>

  <script>
    // Simple fetch – fails hard if the network is down
    async function loadNotes() {
      try {
        const resp = await fetch('/api/notes');
        const data = await resp.json();
        renderNotes(data);
      } catch (err) {
        console.error('Network error:', err);
        document.getElementById('notes-list').innerHTML =
          '<li>❌ Unable to load notes – check your connection</li>';
      }
    }

    function renderNotes(notes) {
      const list = document.getElementById('notes-list');
      list.innerHTML = notes.map(n => `<li>${n.text}</li>`).join('');
    }

    loadNotes();
  </script>
</body>
</html>

If the request to /api/notes fails, the user sees an error message and nothing else. No data, no UI, just frustration.

After: Adding a service worker and a cache‑first strategy

First, we register the worker (still in index.html but after the UI setup):

<script>
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/sw.js')
      .then(reg => console.log('SW registered', reg))
      .catch(err => console.error('SW registration failed', err));
  }
</script>

Now the real spell: sw.js. I’ll use Workbox because it takes care of the boilerplate, but you can write the raw fetch event yourself if you prefer.

// sw.js
import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { CacheFirst, StaleWhileRevalidate } from 'workbox-strategies';
import { CacheableResponsePlugin } from 'workbox-cacheable-response';

// 1️⃣ Precache the core assets (HTML, CSS, JS) during install
precacheAndRoute(self.__WB_MANIFEST);

// 2️⃣ Cache API responses with a CacheFirst strategy
registerRoute(
  ({url}) => url.pathname.startsWith('/api/'),
  new CacheFirst({
    cacheName: 'api-cache',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200] // treat opaque responses as cacheable
      })
    ]
  })
);

// 3️⃣ For everything else (images, fonts) use StaleWhileRevalidate
registerRoute(
  ({request}) => request.destination === 'image' ||
                 request.destination === 'font' ||
                 request.destination === 'style',
  new StaleWhileRevalidate({
    cacheName: 'assets-cache'
  })
);

// Optional: fallback to a custom offline page
registerRoute(
  () => true,
  new NetworkOnly({
    networkTimeoutSeconds: 3
  }),
  'GET'
);

What changed?

The service worker intercepts requests to /api/* and returns a cached copy if it exists—even when the device is offline.
Assets like our HTML, CSS, and JS are precached, so the app loads instantly on repeat visits.
Images and fonts use a stale‑while‑revalidate approach: show the cached version immediately, then update silently in the background.

Common Traps (The “Bosses” to Avoid)

Caching too aggressively – If you cache POST/PUT/PATCH requests with a CacheFirst strategy, you’ll serve stale data and break mutating endpoints. Stick to caching GET requests only, or use a network‑first approach for writes.
Forgetting to update the precache manifest – When you change a file, the build step must regenerate __WB_MANIFEST. Otherwise the service worker will keep serving the old version, and users won’t see your updates. Run your build tool (e.g., workbox-build generateSW) as part of your CI pipeline.

With these two pitfalls dodged, the app now behaves like a trusty sidekick: it shows the latest notes when online, and seamlessly falls back to the last‑known good state when the network vanishes.

Why This New Power Matters

Adopting an offline‑first mindset transforms how users perceive reliability. Instead of blaming “bad connection,” they experience a snappy, consistent UI that just works. This leads to higher engagement, lower bounce rates, and—let’s be honest—a lot less “I’ll try again later” abandonment.

From a business perspective, PWAs cut down on the need to maintain separate native codebases for simple features. You get installability, push notifications, and background sync—all from a single web codebase. And the best part? You can start small: add a service worker to cache your core shell, then gradually cache API responses as you grow comfortable.

So, what’s your next move? Grab a project you’ve been meaning to improve, sprinkle in a service worker, and watch it evolve from a fragile web page into a resilient, offline‑first PWA.

Challenge: Take one page of your app, implement a CacheFirst strategy for its API calls, and try turning off your Wi‑Fi. Does the data still appear? If yes, share your victory (or your debugging tale) in the comments—I’d love to hear how your quest went!

Happy coding, and may your caches always be hot. 🚀

DEV Community