Caching System

Strategy resolution priority

The SW resolves which strategy to apply for each incoming fetch in this priority order:

1. Header override — X-SW-Strategy header on the request
2. Pattern match — first matching glob in strategy.patterns
3. Default — strategy.default value

URL patterns use glob syntax:

Strategy pipeline

All six strategies share the same core building blocks:

• serveFromCache(request) — looks up request in precache or runtime caches, with mode-specific rules for navigation requests
• _fetchWithTimeout(request) — pure fetch with AbortController timeout (no cache lookup, no ETag, no 304 handling)
• cacheResponse(response, request) — stores responses by content-type, skipping runtime when entry exists in precache
• fallback(request) — dispatches to navFallback() for navigation requests; returns 502 Bad Gateway for all other subresources (images, scripts, API calls, etc.)
• navFallback(request) — the HTML fallback chain: precache → runtime-html (SSR only) → per-route → global fallback (SSR only) → inline 503

Per-strategy flow

serveFromCache by mode

Cache rules

• cacheResponse always skips storing in runtime when entry exists in precache (precache is authoritative)
• Tags are recorded in IndexedDB for every cache write (runtime or precache)
• _fetchWithTimeout is a pure fetch + timeout — all caching decisions happen at the strategy level

Reactive strategy

staleTime model

Swoff's staleness model is different from a TTL eviction. It is scoped to a single explicit reactive strategy rather than spread across all strategies:

• Fresh: within staleTime seconds of being cached. The SW serves from cache immediately — no network request.
• Stale: past staleTime. The SW still serves the cached response, but triggers a background refresh (batched and rate-limited). The next request gets fresh data.

This means the user never sees a loading spinner for cached data. The response is always instant from cache; freshness is maintained in the background.

staleTime is reactive-only. It has no meaning on other strategies — each non-reactive strategy has its own simple, predictable contract:

The key insight: staleTime does not evict the entry. It makes the data usable indefinitely while keeping it fresh in the background. Background refreshes are batched (features.refetchQueue.batchSize) with rate limiting (features.refetchQueue.batchDelayMs) to avoid stampedes.

Refresh triggers

The reactive strategy bundles three optional refresh triggers that all gate through staleTime:

Entry lifecycle

When a reactive match is found, the SW registers a reactive entry:

// Inside the SW — automatic
registerReactiveEntry(cacheKey, actualUrl, {
  staleTime: 30,
  refetchInterval: 60,
  refetchOnFocus: true,
  refetchOnReconnect: false,
});

The entry tracks the URL for automatic background refreshes. Intervals are cleaned up on SW deactivation.

Navigation modes

Three modes control how navigation requests are served from cache and what happens when both cache and network fail.

serveFromCache

Each mode follows its own lookup chain for navigation requests:

For non-navigation requests (JS, CSS, API), the same three-step chain applies regardless of mode: runtime cache → precache (content-type must match Accept) → null. No branch decides to hit the network — serveFromCache returns a cached response or null. The strategy decides what to do next.

Fallback chain

When the strategy exhausted all options (network failed + serveFromCache returned null), fallback() dispatches based on request type:

• Navigation requests (sec-fetch-mode: navigate) → delegates to navFallback()
• SSR framework client-nav fetches (Next.js RSC text/x-component, Remix ?_data, SvelteKit __data.json) → delegates to navFallback()
• All other subresources (JS, CSS, images, API calls, fonts, etc.) → returns 502 Bad Gateway with no HTML body

This prevents the old behavior of serving HTML offline pages for non-HTML requests, which caused rendering errors, corrupt asset imports, and broken API responses.

navFallback chain (HTML fallback, navigation only)

The fallback levels broadcast to clients via OFFLINE_FALLBACK_ACTIVATED: "route-fallback", "offline-page", "inline-503". The "spa-shell" level is no longer emitted — SPA shell is served directly from serveFromCache(), not from the fallback chain.

SSR and auto-prefetch

The "ssr" navigation mode is designed for server-rendered applications (Next.js, Remix, Nuxt, SvelteKit, Astro, HTMX). Unlike the old architecture which required separate navigateFirst handlers, SSR mode now falls through to the global caching strategy like all other modes. The key differentiator is auto-prefetch:

When "ssr" mode is enabled, the generated client-injector code intercepts history.pushState() and history.replaceState() and calls prefetchCache(url) for each navigation. This ensures that when the user clicks a client-side link, the SW starts fetching the page in the background before the server responds. The next time the user refreshes or navigates to that page, the cached HTML is available instantly.

The interception is framework-agnostic — every client-side router ultimately calls pushState/replaceState. No framework-specific integration is needed.

All navigation modes use the same standard strategy dispatch for the actual fetch — the mode only controls serveFromCache lookup order and navFallback() chain depth.

HTML cache isolation

A single URL can serve different content types depending on the request context — full page loads return text/html while client-side fetches may return text/x-component (RSC), application/json, or partial HTML. If these were stored at the same cache key, a hard refresh while offline could serve a non-HTML response to the browser.

Swoff isolates HTML responses in their own cache container (CACHE_NAME_RUNTIME_HTML = "swoff-runtime-html"). The cacheResponse function routes by Content-Type:

• text/html → CACHE_NAME_RUNTIME_HTML (HTML-only cache)
• Everything else (RSC, JSON, JS, CSS, images) → CACHE_NAME_RUNTIME (main runtime cache)
• If the URL already exists in precache, the entry is skipped (never stored in runtime) — precache takes precedence

This is framework-agnostic — the rule is simply: "HTML is special for navigation; everything else is normal."

There is no user-facing config — it is always enabled. Both caches participate in eviction, tag invalidation, activate handler cleanup, and online/focus reactive scans.

RSC frameworks (Next.js, TanStack Start)

The ?_rsc=<token> query param is safe to strip via ignoreQueryParams: ["_rsc"] — RSC payloads and HTML pages for the same URL are stored in different caches and never collide.

Offline navigation behavior:

Limitations: Pages never full-loaded cannot be refreshed offline. Dynamic pages require a successful full load to cache their HTML. React's in-memory RSC cache is per-session — a fresh tab or refresh requires the SW or network.

3-tier config resolution

The strategy field resolves through three priority levels:

1. Per-request (highest) — passed as options to fetchWithCache({ strategy }) or useSwoffFetch(), or via X-SW-Strategy header
2. Route pattern — configured in features.serviceWorker.strategy.patterns keyed by URL pattern
3. Global default (lowest) — configured at features.serviceWorker.strategy.default

Reactive-only fields (staleTime, refetchInterval, refetchOnReconnect, refetchOnFocus) resolve through tiers:

Example resolution flow:

• Request to /api/todos with strategy "reactive" → tier 1: X-SW-Stale-Time header? no → tier 2: /api/* has staleTime: 30 → use 30s
• Request to /api/posts with strategy "reactive" (no route match) → tier 1: no header → tier 2: no pattern → tier 3: global staleTime: 0 → use 0s (always stale)

Decision Matrix

navFallback expands to the HTML chain above. Subresource 502 returns new Response(null, { status: 502 }) — no HTML body is served for non-navigation requests.

See the Library Comparison for feature matrices comparing Swoff's caching, offline navigation, prefetch, and write queue against Workbox, Serwist, and other tools.