Building an Offline Experience & Fallbacks

Technical Deep Dive & Specifications

The App Shell Architecture

The App Shell separates static infrastructure from dynamic content:

+-----------------------------------------------------------------------------------+
|                              APP SHELL (PRECACHED)                                |
|  +-----------------------------------------------------------------------------+  |
|  | Header: [ App Logo ]                       [ Notifications ] [ Profile Pic ] |  |
|  +-----------------------------------------------------------------------------+  |
|  | Navigation: [ Home ]   [ Explore ]   [ Library ]   [ Settings ]             |  |
|  +-----------------------------------------------------------------------------+  |
|                                                                                   |
|  +-----------------------------------------------------------------------------+  |
|  |                        DYNAMIC CONTENT VIEWPORT                             |  |
|  |                                                                             |  |
|  |  [ ONLINE ]: Fetches live JSON and populates reactive templates             |  |
|  |                                                                             |  |
|  |  [ OFFLINE ]: Reads local IndexedDB cache or displays offline fallback UI   |  |
|  |                                                                             |  |
|  +-----------------------------------------------------------------------------+  |
+-----------------------------------------------------------------------------------+

1. The Shell: index.html, global.css, app.js, brand icons. Precached on worker install.
2. The Content: Dynamic API payloads, user messages, article bodies. Cached dynamically at runtime.

Navigation Fallback Mechanics

When a user clicks a link to an uncached page (e.g., https://example.com/articles/deep-dive-into-wasm) while offline:

1. The browser initiates a navigation request (request.mode === 'navigate').
2. The Service Worker attempts a network fetch.
3. The network fetch rejects (TypeError: Failed to fetch).
4. The Service Worker catches the rejection and returns caches.match('/offline.html').

                    +--------------------------------+
                    | User Navigates to /article/99  |
                    | (request.mode === 'navigate')  |
                    +--------------------------------+
                                   |
                                   v
                    +--------------------------------+
                    |  Service Worker Interception   |
                    +--------------------------------+
                                   |
                                   v
                    +--------------------------------+
                    |     Attempt Network Fetch      |
                    +--------------------------------+
                                   |
                    +--------------+--------------+
                    | (Network OK)                | (Network Fails / Offline)
                    v                             v
        +-----------------------+     +-----------------------+
        | Return 200 Live Page  |     | Catch Rejection &     |
        | Update dynamic cache  |     | Return /offline.html  |
        +-----------------------+     +-----------------------+

💻 Interactive Code Playground

Starter Code: Complete App Shell + Offline Fallback System

1. File: offline.html (Dedicated Offline Branded Fallback)

2. File: sw.js (App Shell Precaching & Navigation Routing)

3. File: index.html (App Shell Host with Live Network Toast)

Line-by-Line Code Breakdown

• sw.js Line 3 (PRECACHE_MANIFEST): Explicitly enumerates the exact file set required to render the application's core visual framework and offline message.
• sw.js Line 38 (if (request.mode === 'navigate')): Detects document-level URL changes in the browser address bar, ensuring that sub-resource fetch failures do not trigger full offline page replacements.
• sw.js Line 46 (return caches.match('/offline.html')): The guaranteed offline fallback guarantee; if both the live network and the requested cached document miss, the branded offline UI renders.
• index.html Line 47–59 (window.addEventListener('offline' | 'online')): Coordinates immediate visual feedback in the UI thread when hardware connectivity changes.

Expected Browser Render Output

const SHELL_CACHE = 'app-shell-v1';
const PRECACHE_MANIFEST = [
  '/',
  '/index.html',
  '/offline.html',
  '/styles/app.css',
  '/scripts/app.js',
  '/icons/logo.svg'
];

// Precache App Shell
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(SHELL_CACHE).then((cache) => {
      console.log('[SW] Precaching complete App Shell & offline fallback.');
      return cache.addAll(PRECACHE_MANIFEST);
    })
  );
  self.skipWaiting();
});

// Purge Old Shells
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) => {
      return Promise.all(
        keys.map((key) => {
          if (key !== SHELL_CACHE) {
            return caches.delete(key);
          }
        })
      );
    }).then(() => self.clients.claim())
  );
});

// Intercept Navigations and Assets
self.addEventListener('fetch', (event) => {
  const { request } = event;

  // Case 1: HTML Page Navigation
  if (request.mode === 'navigate') {
    event.respondWith(
      fetch(request)
        .catch(async () => {
          // If offline, check if the specific page is cached, otherwise serve offline.html
          const cachedPage = await caches.match(request);
          if (cachedPage) {
            return cachedPage;
          }
          return caches.match('/offline.html');
        })
    );
    return;
  }

  // Case 2: Static App Shell Assets
  event.respondWith(
    caches.match(request).then((cachedResponse) => {
      return cachedResponse || fetch(request);
    })
  );
});

(User visits /news/today while online):
[Online View]: Full live news article loads normally.

(User switches to Airplane Mode and refreshes):
[Offline View]: App Shell loads instantly, offline toast appears:
[ ⚠️ No Internet Connection. Working Offline. ]

(User clicks a link to an uncached page /deep-analysis while offline):
[Offline Fallback]: 
+---------------------------------------------+
|                     📡                      |
|          You Are Currently Offline          |
| The page you requested is not saved in your |
| offline cache. Check connection and retry.  |
|            [ Retry Connection ]             |
+---------------------------------------------+