Navigation Caching

How Swoff handles page navigation — what happens when a user clicks a link or types a URL.

Works automatically. Navigation caching is active the moment you call initServiceWorker() — no other imports, no API calls, no framework-specific code. Configured entirely through swoff.config.json. Every ecosystem (React, vanilla, no-bundler, HTMX) gets this for free.

For the internal mechanics of serveFromCache, the fallback chain, and per-mode lookup rules, see the Caching System architecture.

Preconditions

• Service worker registered and controlling the page (see Service Worker guide)
• initServiceWorker() called in your app entry — that's it

Status

Already on by default. After swoff init, navigation mode is "spa" with preload enabled.

Navigation modes

Three modes control offline navigation behavior. For the internal serveFromCache lookup rules, fallback chain depth, and SSR auto-prefetch internals, see the Caching System architecture.

Config

{
  "features": {
    "serviceWorker": {
      "navigation": {
        "mode": "spa",
        "preload": true,
        "fallback": "/offline",
        "precacheRoutes": [],
        "rules": []
      }
    }
  }
}

• navigation.mode — "spa", "ssr", or "default". See the architecture page for per-mode lookup and fallback details.

• navigation.preload — when true, the SW enables Navigation Preload during activation. The browser starts the network request in parallel with SW startup; the SW races the preload response against half the fetch timeout.

• navigation.fallback — URL path of an HTML page to serve as the offline fallback. In SPA mode, serveFromCache() serves it for any navigation request (app shell pattern). In SSR/default mode, used only in navFallback() after everything else has been tried. Empty string means no fallback (browser shows its own offline page).

• navigation.precacheRoutes — array of URL paths to precache in the background after activation. Example: ["/", "/about", "/offline"]. Cached alongside scanned build assets from precacheDirs.

• navigation.rules — per-route fallback paths, checked inside navFallback() after precache and runtime-html but before the global fallback path. Each entry has:

  • match — glob pattern for navigation URLs
  • fallback — URL path from precache to serve as fallback

  Does not affect normal cached operation — only applies when the network and cache both fail.

Framework adapters

useSwoffNetwork now lives in the Connectivity & Storage guide.

useSwoffAnalytics

Tracks offline fallback events for analytics: { lastEvent, events, clear }.

The SW broadcasts OFFLINE_FALLBACK_ACTIVATED via postMessage to all clients. The injector relays it as a window event, giving you two ways to listen:

Events listened to:

Detail shape: { route, fallbackLevel: "route-fallback" | "offline-page" | "inline-503", timestamp }

If your framework already has a useSwoffAnalytics adapter (React, Vue, Svelte), the CLI generates it into swoff/adapters/. To create adapters for any other framework, see the Blueprint for the event reference.

Related

• Caching System architecture — serveFromCache per-mode lookup rules, fallback chain, SSR auto-prefetch internals
• Comparison: SW Toolkits — offline navigation feature matrix