Building PWAs: Offline-First Web Apps Like a Jedi

The Quest Begins (The "Why")

Ever opened a web app on a spotty train ride and watched it sputter to a blank screen? I’ve been there, staring at a loading spinner while my coffee went cold, wishing the app would just remember what I’d already done. That frustration sparked my quest: how do we make a web app work when the network decides to take a nap?

I started with a simple weather widget. It fetched data from an API, rendered a nice card, and… died the moment the Wi‑Fi dropped. Users complained, I felt helpless, and the idea of “offline‑first” seemed like a myth reserved for native apps. Little did I know, the browser already held a powerful spell—service workers—waiting for someone to whisper the right incantation.

The Revelation (The Insight)

The breakthrough came when I realized offline isn’t about blocking network requests; it’s about intercepting them and serving a fallback when the network fails. A service worker is a script that runs in the background, separate from your page, and can cache assets, API responses, or even whole pages. When the network is unavailable, the worker steps in and says, “Hey, I’ve got you covered.”

Think of it like a trusty sidekick who keeps a stash of supplies for when the hero’s journey gets rough. The first time I saw a cached response appear instantly—no spinner, no error—I felt like I’d just unlocked a secret level.

Wielding the Power (Code & Examples)

The Struggle: Naïve Fetch

// app.js – before any offline logic
async function fetchWeather(city) {
  const response = await fetch(`/api/weather?city=${city}`);
  const data = await response.json();
  renderWeather(data);
}

If the request fails, the UI just shows an error. No retry, no cache, no mercy.

The Trap: Forgetting to Register

A common pitfall is writing the service worker but never telling the browser to use it. The worker sits idle, and you wonder why nothing changed.

// Wrong! Missing registration
// navigator.serviceWorker.register('/sw.js'); // ← forgotten

The Victory: A Simple Service Worker

First, register the worker from your main script (once per page load).

// app.js – registration
if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js')
      .then(reg => console.log('SW registered:', reg.scope))
      .catch(err => console.error('SW registration failed:', err));
  });
}

Now the worker (/sw.js) does the heavy lifting.

// sw.js – the cache‑first strategy
const CACHE_NAME = 'weather-app-v1';
const API_BASE = '/api/weather';

self.addEventListener('install', event => {
  // Cache static assets (HTML, CSS, JS) on install
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll([
        '/',
        '/index.html',
        '/styles.css',
        '/app.js',
        '/icon-192.png',
        '/icon-512.png'
      ]))
  );
});

self.addEventListener('fetch', event => {
  const { request } = event;
  const url = new URL(request.url);

  // 1️⃣ Cache‑first for static assets
  if (url.origin === location.origin && !url.pathname.startsWith(API_BASE)) {
    event.respondWith(
      caches.match(request)
        .then(cached => cached || fetch(request))
    );
    return;
  }

  // 2️⃣ Network‑first with fallback for API calls
  if (url.pathname.startsWith(API_BASE)) {
    event.respondWith(
      fetch(request)
        .then(response => {
          // Clone because response is a stream; we need one for cache, one for client
          const clone = response.clone();
          caches.open(CACHE_NAME).then(cache => cache.put(request, clone));
          return response;
        })
        .catch(() => caches.match(request)) // if network fails, serve cached copy
    );
    return;
  }

  // 3️⃣ Default to network for everything else
  event.respondWith(fetch(request));
});

What changed?

• On install, we precache the UI shell.
• For API requests, we try the network first; if it succeeds, we store a copy for later.
• If the network fails, we serve the most recent cached response—giving users instant data even offline.

Another Common Mistake: Not Updating the Cache

If you never change CACHE_NAME, the browser will keep using the old worker and stale assets forever. Bump the version whenever you modify cached files.

// Change this whenever you update static assets
const CACHE_NAME = 'weather-app-v2'; // ← incremented

When the new worker activates, call clients.claim() to take control of open pages immediately.

self.addEventListener('activate', event => {
  event.waitUntil(
    caches.keys().then(keys =>
      Promise.all(
        keys.filter(key => key !== CACHE_NAME)
          .map(key => caches.delete(key))
      )
    ).then(() => self.clients.claim())
  );
});

Now every time you deploy a fresh build, the old cache gets purged and users get the latest code.

Why This New Power Matters

With this setup, your PWA behaves like a native app: it loads instantly on repeat visits, works on flaky connections, and even shows meaningful content when the user is completely offline. Imagine a traveler checking their itinerary on a mountain trail with zero bars—still seeing their schedule, maps, or notes. That’s the kind of reliability that turns casual users into loyal fans.

You’ve also opened the door to background sync, push notifications, and periodic background fetch—features that keep your app alive even when the tab isn’t front‑and‑center. The web finally feels less like a fragile document and more like a resilient, installable experience.

Your Turn: Embark on the Quest

Grab a small project—maybe a todo list or a news feed—and slap on a service worker using the pattern above. Start with precaching your shell, then add a network‑first fallback for your API. Break something on purpose (turn off Wi‑Fi) and watch your app keep ticking.

What feature will you make offline‑first first? Share your wins (or your epic fails) in the comments—I’d love to hear how your journey goes! 🚀