Request.isReloadNavigation

at a glance

why it exists

Service worker fetch event handlers intercept all navigation requests — but they can't natively tell a reload apart from a fresh forward navigation. The common workaround was reading event.request.cache and checking for "reload", or inspecting request headers for Cache-Control: no-cache, both of which are unreliable across browsers and request modes.

The deprecated FetchEvent.isReload property filled this gap in early service worker implementations, but it was removed from the spec because it lived in the wrong place (the event, not the request object). Request.isReloadNavigation is the standardised, interoperable replacement — available on any Request object, not just in a fetch event handler.

shape of the API

Request.isReloadNavigation

Related: Request.isHistoryNavigation

A companion boolean, isHistoryNavigation, is true when the request was triggered by a back/forward traversal (history.back(), history.forward(), history.go(n), browser history buttons). It shipped separately and has its own MDN reference page.

example

Network-first on reload, cache-first otherwise

// service-worker.js
self.addEventListener("fetch", (event) => {
  if (event.request.mode !== "navigate") return;

  if (event.request.isReloadNavigation) {
    // User explicitly reloaded — serve fresh from network.
    event.respondWith(
      fetch(event.request).catch(() => caches.match(event.request))
    );
  } else {
    // Regular navigation — serve from cache if available.
    event.respondWith(
      caches.match(event.request).then(
        (cached) => cached ?? fetch(event.request)
      )
    );
  }
});

Log reload rate to analytics

self.addEventListener("fetch", (event) => {
  if (event.request.mode === "navigate") {
    analytics.log("navigation", {
      url: event.request.url,
      isReload: event.request.isReloadNavigation,
      isHistory: event.request.isHistoryNavigation,
    });
  }
});

Bypass service worker cache for reload only

self.addEventListener("fetch", (event) => {
  const req = event.request;

  // For reload navigations, skip the SW cache entirely.
  if (req.isReloadNavigation) {
    // Construct a new Request with cache: "no-cache" to force revalidation.
    event.respondWith(fetch(new Request(req, { cache: "no-cache" })));
    return;
  }

  event.respondWith(
    caches.open("v1").then((cache) =>
      cache.match(req).then((cached) => cached ?? fetch(req))
    )
  );
});

browser support

see also

• WHATWG Fetch spec — dom-request-isreloadnavigation
• MDN: Request.isHistoryNavigation — the companion property for back/forward traversals
• MDN: FetchEvent — service worker fetch event
• MDN: Service Worker API