Jeff Posnick on web.dev

ES modules in service workers

2021-05-13T00:00:00Z

Background #

ES modules have been a developer favorite for a while now. In addition to a number of other benefits, they offer the promise of a universal module format where shared code can be released once and run in browsers and in alternative runtimes like Node.js. While all modern browsers offer some ES module support, they don't all offer support everywhere that code can be run. Specifically, support for importing ES modules inside of a browser's service worker is just starting to become more widely available.

This article details the current state of ES module support in service workers across common browsers, along with some gotchas to avoid, and best practices for shipping backwards-compatible service worker code.

Use cases #

The ideal use case for ES modules inside of service workers is for loading a modern library or configuration code that's shared with other runtimes that support ES modules.

Attempting to share code in this way prior to ES modules entailed using older "universal" module formats like UMD that include unneeded boilerplate, and writing code that made changes to globally exposed variables.

Scripts imported via ES modules can trigger the service worker update flow if their contents change, matching the behavior of importScripts().

Current limitations #

Static imports only #

ES modules can be imported in one of two ways: either statically, using the import ... from '...' syntax, or dynamically, using the import() method. Inside of a service worker, only the static syntax is currently supported.

This limitation is analogous to a similar restriction placed on importScripts() usage. Dynamic calls to importScripts() do not work inside of a service worker, and all importScripts() calls, which are inherently synchronous, must complete before the service worker completes its install phase. This restriction ensures that the browser knows about, and is able to implicitly cache, all JavaScript code needed for a service worker's implementation during installation.

Eventually, this restriction might be lifted, and dynamic ES module imports may be allowed. For now, ensure that you only use the static syntax inside of a service worker.

What about other workers? #

Support for ES modules in "dedicated" workers—those constructed with new Worker('...', {type: 'module'})—is more widespread, and has been supported in Chrome and Edge since version 80, as well as recent versions of Safari. Both static and dynamic ES module imports are supported in dedicated workers.

Chrome and Edge have supported ES modules in shared workers since version 83, but no other browser offers support at this time.

No support for import maps #

Import maps allow runtime environments to rewrite module specifiers, to, for example, prepend the URL of a preferred CDN from which the ES modules can be loaded.

While Chrome and Edge version 89 and above support import maps, they currently cannot be used with service workers.

Browser support #

Browser support

Chrome 61, Supported 61
Firefox 60, Supported 60
Edge 16, Supported 16
Safari 10.1, Supported 10.1

Source

ES modules in service workers are supported in Chrome and Edge starting with version 91.

Safari added support in the Technology Preview 122 Release, and developers should expect to see this functionality released in the stable version of Safari in the future.

Example code #

This is a basic example of using a shared ES module in a web app's window context, while also registering a service worker that uses the same ES module:

// Inside config.js:
export const cacheName = 'my-cache';

// Inside your web app:
<script type="module">
  import {cacheName} from './config.js';
  // Do something with cacheName.

  await navigator.serviceWorker.register('es-module-sw.js', {
    type: 'module',
  });
</script>

// Inside es-module-sw.js:
import {cacheName} from './config.js';

self.addEventListener('install', (event) => {
  event.waitUntil((async () => {
    const cache = await caches.open(cacheName);
    // ...
  })());
});

Backwards compatibility #

The above example would work fine if all browsers supported ES modules in service workers, but as of this writing, that's not the case.

To accommodate browsers that don't have built-in support, you can run your service worker script through an ES module-compatible bundler to create a service worker that includes all of the module code inline, and will work in older browsers. Alternatively, if the modules you're attempting to import are already available bundled in IIFE or UMD formats, you can import them using importScripts().

Once you have two versions of your service worker available—one that uses ES modules, and the other that doesn't—you'll need to detect what the current browser supports, and register the corresponding service worker script. The best practices for detecting support are currently in flux, but you can follow the discussion in this GitHub issue for recommendations.

Photo by Vlado Paunovic on Unsplash

Handling range requests in a service worker

2020-10-06T00:00:00Z

Some HTTP requests contain a Range: header, indicating that only a portion of the full resource should be returned. They're commonly used for streaming audio or video content to allow smaller chunks of media to be loaded on demand, instead of requesting the entirety of the remote file all at once.

A service worker is JavaScript code that sits in between your web app and the network, potentially intercepting outgoing network requests and generating responses for them.

Historically, range requests and service workers haven't played nicely together. It's been necessary to take special steps to avoid bad outcomes in your service worker. Fortunately, this is starting to change. In browsers exhibiting the correct behavior, range requests will "just work" when passing through a service worker.

What's the issue? #

Consider a service worker with the following fetch event listener, which takes every incoming request and passes it to the network:

self.addEventListener('fetch', (event) => {
  // The Range: header will not pass through in
  // browsers that behave incorrectly.
  event.respondWith(fetch(event.request));
});

In browsers with the incorrect behavior, if event.request included a Range: header, that header would be silently dropped. The request that was received by the remote server would not include Range: at all. This would not necessarily "break" anything, since a server is technically allowed to return the full response body, with a 200 status code, even when a Range: header is present in the original request. But it would result in more data being transferred than is strictly needed from the perspective of the browser.

Developers who were aware of this behavior could work around it by explicitly checking for the presence of a Range: header, and not calling event.respondWith() if one is present. By doing this, the service worker effectively removes itself from the response generation picture, and the default browser networking logic, which knows how to preserve range requests, is used instead.

self.addEventListener('fetch', (event) => {
  // Return without calling event.respondWith()
  // if this is a range request.
  if (event.request.headers.has('range')) {
    return;
  }

  event.respondWith(fetch(event.request));
});

It's safe to say that most developers were not aware of the need to do this, though. And it wasn't clear why that should be required. Ultimately, this limitation was due to browsers needing to catch up to changes in the underlying specification, which added support for this functionality.

What's been fixed? #

Browsers that behave correctly preserve the Range: header when event.request is passed to fetch(). This means the service worker code in my initial example will allow the remote server to see the Range: header, if it was set by the browser:

self.addEventListener('fetch', (event) => {
  // The Range: header will pass through in browsers
  // that behave correctly.
  event.respondWith(fetch(event.request));
});

The server now gets a chance to properly handle the range request and return a partial response with a 206 status code.

Which browsers behave correctly? #

Recent versions of Safari have the correct functionality. Chrome and Edge, starting with version 87, behave correctly as well.

As of this October 2020, Firefox has not yet fixed this behavior, so you may still need to account for it while deploying your service worker's code to production.

Checking the "Include range header in network request" row of the Web Platform Tests dashboard is the best way to confirm whether or not a given browser has corrected this behavior.

What about serving range requests from the cache? #

Service workers can do much more than just pass a request through to the network. A common use case is to add resources, like audio and video files, to a local cache. A service worker can then fulfill requests from that cache, bypassing the network entirely.

All browsers, including Firefox, support inspecting a request inside a fetch handler, checking for the presence of the Range: header, and then locally fulfilling the request with a 206 response that comes from a cache. The service worker code to properly parse the Range: header and return only the appropriate segment of the complete cached response is not trivial, though.

Fortunately, developers who want some help can turn to Workbox, which is a set of libraries that simplifies common service worker use cases. The workbox-range-request module implements all the logic necessary to serve partial responses directly from the cache. A full recipe for this use case can be found in the Workbox documentation.

The hero image on this post is by Natalie Rhea Riggs on Unsplash.

Handling navigation requests

2020-07-13T00:00:00Z

Navigation requests are requests for HTML documents made by your browser whenever you enter a new URL in the navigation bar, or follow a link on a page taking you to a new URL. This is where service workers make their biggest impact on performance: if you use a service worker to respond to navigation requests without waiting for the network, you can ensure that navigations are reliably fast, in addition to being resilient when the network is unavailable. This is the single biggest performance win that comes from a service worker, versus what's possible with HTTP caching.

As detailed in the Identify resources loaded from the network guide, a navigation request is the first of potentially many requests made in the "waterfall" of network traffic. The HTML that you load via a navigation request kicks off the flow of all other requests for subresources like images, scripts, and styles.

Inside of a service worker's fetch event handler, you can determine whether a request is a navigation by checking the request.mode property on the FetchEvent. If it's set to 'navigate', then it's a navigation request.

As a general rule, do not use long-lived Cache-Control headers to cache the HTML response for a navigation request. They should normally be satisfied via the network, with Cache-Control: no-cache, to ensure that the HTML, along with the chain of subsequent network requests, is (reasonably) fresh. Going against the network each time the user navigates to a new page unfortunately means that each navigation might be slow. At the very least, it means that it won't be reliably fast.

Different approaches for architectures #

Figuring out how to respond to navigation requests while avoiding the network can be tricky. The right approach depends very much on your web site's architecture and the number of unique URLs that users might navigate to.

While there's no one-size-fits all solution, the following general guidelines should help you decide which approach is the most viable.

Small static sites #

If your web app consists of a relatively small number (think: a couple of dozen) unique URLs, and each of those URLs corresponds to a different static HTML file, then one viable approach is to just cache all of those HTML files, and respond to navigation requests with the appropriate cached HTML.

Using precaching, you can cache the HTML in advance, as soon as the service worker is installed, and update the cached HTML each time you rebuild your site and redeploy your service worker.

Alternatively, if you would rather avoid precaching all of your HTML—perhaps because users tend to navigate to only a subset of URLs on your site—you can use a stale-while-revalidate runtime caching strategy. Be careful about this approach, though, as each individual HTML document is cached and updated separately. Using runtime caching for HTML is most appropriate if you have a small number of URLs that are revisited frequently by the same set of users, and if you feel comfortable about those URLs being revalidated independently of each other.

Single-page apps #

A single-page architecture is frequently used by modern web applications. In it, client-side JavaScript modifies the HTML in response to user actions. This model uses the History API to modify the current URL as the user interacts with the web app, leading to what's effectively a "simulated" navigation. While subsequent navigations might be "fake", the initial navigation is real, and it's still important to make sure that it isn't blocked on the network.

Fortunately, if you're using the single-page architecture, there's a straightforward pattern to follow for serving the initial navigation from the cache: the application shell. In this model, your service worker responds to navigation requests by returning the same, single HTML file that has already been precached—regardless of the URL being requested. This HTML should be bare-bones, consisting of, perhaps, a generic loading indicator or skeleton content. Once the browser has loaded this HTML from the cache, your existing client-side JavaScript takes over, and renders the correct HTML content for the URL from the original navigation request.

Workbox provides the tools that you need to implement this approach; the navigateFallback option allows you to specify which HTML document to use as your app shell, along with an optional allow and deny list to limit this behavior to a subset of your URLs.

Multi-page apps #

If your web server generates your site's HTML dynamically, or if you have more than a few dozen unique pages, then it's much harder to avoid the network when handling navigation requests. The advice in Everything else will likely apply to you.

But for a certain subset of multi-page apps, you might be able to implement a service worker that fully replicates the logic used in your web server to generate HTML. This works best if you can share routing and templating information between the server and service worker environments, and in particular, if your web server uses JavaScript (without relying on Node.js-specific features, like file system access).

If your web server falls into that category and you would like to explore one approach to moving HTML generation off the network and into your service worker, the guidance in Beyond SPAs: alternative architectures for your PWA can get you started.

Everything else #

If you can't respond to navigation requests with cached HTML, you must take steps to ensure that adding a service worker to your site (to handle other, non-HTML requests) doesn't end up slowing down your navigations. Starting up the service worker without using it to respond to a navigation request will introduce a small amount of latency (as explained in Building Faster, More Resilient Apps with Service Worker). You can mitigate this overhead by enabling a feature called navigation preload, and then using the network response that's been preloaded inside of your fetch event handler.

Workbox provides a helper library that feature-detects whether navigation preload is supported, and if so, simplifies the process of telling your service worker to use the network response.

Photo by Aaron Burden on Unsplash,

Adaptive loading with service workers

2020-06-23T00:00:00Z

Users access websites through a wide variety of devices and network connections. Even in major cities, where mobile networks are fast and reliable, one can end up experiencing slower load times, for example, when commuting in the subway, in a car, or just when moving around. In regions like emerging markets, this phenomenon is even more common, not only due to unreliable networks, but also because devices tend to have less memory and CPU processing power.

Adaptive loading is a web performance pattern that lets you adapt your site based on the user's network and device conditions.

The adaptive loading pattern is made possible by service workers, the Network Information API, the Hardware Concurrency API, and the Device Memory API. In this guide we explore how you can use service workers and the Network Information API to achieve an adaptive loading strategy.

Production case #

Terra is one of the biggest media companies in Brazil. It has a large user base, coming from a wide variety of devices and networks.

To provide a more reliable experience to all their users, Terra combines service workers and the Network Information API to deliver lower quality images to users on 2G or 3G connections.

The company also found that the scripts and assets (like banners) loaded by ad networks were especially detrimental to users navigating in 3G or slower connections.

As is the case with many publishers, Terra serves AMP versions of their pages to users coming from search engines and other link sharing platforms. AMP pages are usually lightweight and help mitigate the impact of ads in performance by deprioritizing their load with respect to the main content of the page.

Taking that into consideration, Terra decided to start serving AMP versions of their pages not only to users coming from search engines, but also to those navigating their site in 3G connections or slower.

To achieve that, they use the Network Information API in the service worker to detect if the request comes from 3G or slower. If that's the case, they change the URL of the page to request the AMP version of the page instead.

Thanks to this technique, they send 70% less bytes to users on slower connections. The time spent in AMP pages is higher for 3G users and ads in AMP pages have a better CTR (click-through-rate) for that group.

Implement adaptive loading with Workbox #

In this section we'll explore how Workbox can be used to implement adaptive loading strategies.

Workbox provides several runtime caching strategies out of the box. They are used to indicate how the service worker generates a response after receiving a fetch event.

For example, in a Cache First strategy the Request will be fulfilled using the cached response (if available). If there isn't a cached response, the Request will be fulfilled by a network request and the response will be cached.

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';

registerRoute(
  new RegExp('/img/'),
  new CacheFirst()
);

Caching strategies can be customized with Workbox plugins. These allow you to add additional behaviors by manipulating requests and responses during the lifecycle of a request. Workbox has several built-in plugins for common cases and APIs, but you can also define a custom plugin, and introduce some custom logic of your choice.

To achieve adapting loading, define a custom plugin, called, for example, adaptiveLoadingPlugin:

const adaptiveLoadingPlugin = {
  requestWillFetch: async ({request}) => {
    const urlParts = request.url.split('/');
    let imageQuality;

    switch (
      navigator && navigator.connection
        ? navigator.connection.effectiveType
        : ''
    ) {
      //...
      case '3g':
        imageQuality = 'q_30';
        break;
      //...
    }

    const newUrl = urlParts
      .splice(urlParts.length - 1, 0, imageQuality)
      .join('/')
      .replace('.jpg', '.png');
    const newRequest = new Request(newUrl.href, {headers: request.headers});

    return newRequest;
  },
};

The previous code does the following:

Implements a requestWillFetch() callback: This is called whenever a network request is about to be made, so you can alter the Request.
Checks the connection type, by using the Network Information API. Based on the status of the network, it creates a new URL part, indicating the quality of the image to fetch (e.g. q_30 for 3G users).
Creates a new URL based on the dynamic newPart value, and returns the new Request to be made, based on that URL.

Next, pass the plugin to a cacheFirst strategy containing a regular expression to match image URLs (e.g. /img/):

workbox.routing.registerRoute(
  new RegExp('/img/'),
  workbox.strategies.cacheFirst({
    cacheName: 'images',
    plugins: [
      adaptiveLoadingPlugin,
      workbox.expiration.Plugin({
        maxEntries: 50,
        purgeOnQuotaError: true,
      }),
    ],
  }),
);

As a result, when requests for images are intercepted, the runtime caching strategy will try to fulfill the request from the cache. If it's not available, it will run the logic in the plugin, to decide which image quality to fetch from the network.

Finally the response will be persisted in the cache, and sent back to the page.

Cloudinary Workbox Plugin #

Cloudinary, a video and image hosting service, has a Workbox Plugin that encapsulates the functionality explained in the previous section, making it even easier to implement.

The plugin is designed to work with the Workbox webpack plugin. To implement it, use the GenerateSW() class:

new workboxPlugin.GenerateSW({
  swDest: 'sw.js',
  importScripts: ['./cloudinaryPlugin.js'],
  runtimeCaching: [
    {
      urlPattern: new RegExp('^https://res.cloudinary.com/.*/image/upload/'),
      handler: 'CacheFirst',
      options: {
        cacheName: 'cloudinary-images',
        plugins: [
          {
            requestWillFetch: async ({request}) =>
              cloudinaryPlugin.requestWillFetch(request),
          },
        ],
      },
    },
  ],
});

The previous code does the following:

Uses the GenerateSW() class to configure webpack to generate a service worker in the destination indicated in swDest.
Imports the cloudinary plugin script.
Defines a Cache First runtime caching strategy for requests for images to the Cloudinary CDN.
Passes the Cloudinary Workbox Plugin to adjust the image quality according to the network conditions.

Explore more adaptive loading strategies #

You can go beyond this, by mapping device signals, like hardware concurrency and device memory to device categories and then serving different assets depending on the device type (low-, mid- or high-end).

App shell UX with service workers and streams

2020-06-23T00:00:00Z

Single-page app (SPA) is an architectural pattern in which the browser runs JavaScript code to update the existing page when the user visits a different section of the site, as opposed to loading an entire new page.

This means that the web app doesn't perform an actual page reload. The History API is used instead to navigate back and forth through the user's history and manipulate the contents of the history stack.

Using this type of architecture can provide an app shell UX that's fast, reliable, and usually consumes less data when navigating.

In multi-page apps (MPAs) each time a user navigates to a new URL, the browser progressively renders HTML specific to that page. This means a full page refresh every time you visit a new page.

While both are equally valid models to use, you might want to bring some of the benefits of the app shell UX of SPAs to your existing MPA site. In this article we'll analyze how you can achieve an SPA-like architecture in multi-page apps by combining partials, service workers, and streams.

Production case #

DEV is a community where software developers write articles, take part in discussions, and build their professional profiles.

Their architecture is a multi-page app based on traditional backend templating through Ruby on Rails. Their team was interested in some of the benefits of an app shell model, but didn't want to undertake a major architectural change or move away from their original tech stack.

Here's how their solution works:

First, they create partials of their home page for the header and the footer (shell_top.html and shell_bottom.html) and deliver them as standalone HTML snippets with an endpoint. These assets are added to the cache at the service worker install event (what's commonly referred to as precaching).
When a navigation request is intercepted by the service worker, they create a streamed response by combining the cached header and footer with the main page content that just came from the server. The body is the only actual part of the page that requires fetching data from the network.

The key element of this solution is the usage of streams, which enables incremental creations and updates of data sources. The Streams API also provides an interface for reading or writing asynchronous chunks of data, only a subset of which might be available in memory at any given time. This way, the header of the page can be rendered as soon as it's picked from the cache, while the rest of the content is being fetched from the network. As a result, the navigation experience is so fast that users don't perceive an actual page refresh, only the new content (the body) being updated.

The resulting UX is similar to the app shell UX pattern of SPAs, implemented on a MPA site.

Implement an app shell UX architecture in MPAs with Workbox #

In this section we'll cover a summary of the different parts involved in implementing an app shell UX architecture in MPAs. For a more detailed post on how to implement this on a real site, check out Beyond SPAs: alternative architectures for your PWA.

The server #

Partials #

The first step is to adopt a site structure based on HTML partials. These are just modular pieces of your pages that can be reused across your site and also delivered as standalone HTML snippets.

The head partial can contain all the logic needed to style and render the header of the page. The navbar partial can contain the logic for the navigation bar, the footer partial the code that needs to execute there, and so forth.

The first time the user visits the site, your server generates a response by assembling the different parts of the page:

app.get(routes.get('index'), async (req, res) => {
  res.write(headPartial + navbarPartial);
  const tag = req.query.tag || DEFAULT_TAG;
  const data = await requestData(…);
  res.write(templates.index(tag, data.items));
  res.write(footPartial);
  res.end();
});

By using the res (response) object's write() method, and referencing locally stored partial templates, the response can be streamed immediately, without getting blocked by any external data source. The browser takes this initial HTML and renders a meaningful interface and loading message right away.

The next portion of the page uses API data, which involves a network request. The web app can't render anything else until it gets a response back and processes it, but at least users aren't staring at a blank screen while they wait.

The service worker #

The first time a user visits a site, the header of the page will be rendered faster, without having to wait for the body of the page. The browser still needs to go to the network to fetch the rest of the page.

After the first page load, the service worker is registered, allowing you to fetch the partials for the different static parts of the page (header, navbar, footer, etc.) from the cache.

Precaching static assets #

The first step is to cache the partial HTML templates, so they are immediately available. With Workbox precaching you can store these files at the install event of the service worker and keep them up to date when changes are deployed to the web app.

Depending on the build process, Workbox has different solutions to generate a service worker and indicate the list of files to precache, including webpack and gulp plugins, a generic node module and a command line interface.

For a partials configuration like the one described earlier, the resulting service worker file should contain something similar to the following:

workbox.precaching.precacheAndRoute([
  {
    url: 'partials/about.html',
    revision: '518747aad9d7e',
  },
  {
    url: 'partials/foot.html',
    revision: '69bf746a9ecc6',
  },
  // etc.
]);

Streaming #

Next, add the service worker logic so that the precached partial HTML can be sent back to the web app immediately. This is a crucial part of being reliably fast. Using the Streams API within our service worker makes that possible. Workbox Streams abstracts the details of how streaming works. The package lets you pass to the library a mix of streaming sources, both from caches and runtime data that might come from the network. Workbox takes care of coordinating the individual sources and stitching them together into a single, streaming response.

First, set up the strategies in Workbox to handle the different sources that will make up the streaming response.

const cacheStrategy = workbox.strategies.cacheFirst({
  cacheName: workbox.core.cacheNames.precache,
});

const apiStrategy = workbox.strategies.staleWhileRevalidate({
  cacheName: API_CACHE_NAME,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
  ],
});

The first strategy reads data that's been precached, like the partial HTML templates.
The second strategy implements the stale-while-revalidate caching logic, along with least-recently-used cache expiration logic once we reach 50 entries.

Next, tell Workbox how to use the strategies to construct a complete, streaming response, by passing in an array of sources as functions to execute immediately:

workbox.streams.strategy([
  () => cacheStrategy.handle({
      request: new Request(getCacheKeyForURL("/head.html")),
    }),
  () => cacheStrategy.handle({
      request: new Request(getCacheKeyForURL("/navbar.html")),
    }),
  async ({event, url}) => {
    const tag = url.searchParams.get('tag') || DEFAULT_TAG;
    const listResponse = await apiStrategy.handle(…);
    const data = await listResponse.json();
    return templates.index(tag, data.items);
  },
  () => cacheStrategy.handle({
      request: new Request(getCacheKeyForURL("/foot.html")),
    }),
]);

The first two sources are precached partial templates read directly from the service worker's cache, so they'll always be available immediately.
The next source function fetches data from the network, and processes the response into the HTML that the web app expects.
Finally, a cached copy of the footer and closing HTML tags is streamed to complete the response.

Workbox takes the result from each source and streams it to the web app, in sequence, only delaying if the next function in the array hasn't completed yet. As a result, the user immediately sees the page being painted. The experience is so fast that when navigating the header stays in its position without making the user perceive the full page refresh. This is very similar to the UX that the app shell SPA model provides.

Instant navigation experiences

2020-06-23T00:00:00Z

Performing a task on a site commonly involves several steps. For example, purchasing a product in an e-commerce website might involve searching for a product, picking an item from the list of results, adding the item to the cart, and completing the operation by checking out.

In technical terms, moving through different pages means making a navigation request. As a general rule, you don't want to use long-lived Cache-Control headers to cache the HTML response for a navigation request. They should normally be satisfied via the network, with Cache-Control: no-cache, to ensure that the HTML, along with the chain of subsequent network requests, is (reasonably) fresh. Having to go against the network each time the user navigates to a new page unfortunately means that each navigation might be slow—at the very least, it means that it won't be reliably fast.

To speed up these requests, if you can anticipate the user's action, you can request these pages and assets beforehand and keep them in the cache for a short period of time until the user clicks on these links. This technique is called prefetching and it's commonly implemented by adding <link rel="prefetch"> tags to pages, indicating the resource to prefetch.

In this guide we'll explore different ways in which service workers can be used as a complement of traditional prefetching techniques.

Production cases #

MercadoLibre is the biggest e-commerce site in Latin America. To speed up navigations, they dynamically inject <link rel="prefetch"> tags in some parts of the flow. For example, in listing pages, they fetch the next result page as soon as the user scrolls to the bottom of the listing:

Prefetched files are requested at the "Lowest" priority and stored in the HTTP cache or the memory cache (depending on whether the resource is cacheable or not), for an amount of time that varies by browsers. For example, as of Chrome 85, this value is 5 minutes. Resources are kept around for five minutes, after which the normal Cache-Control rules for the resource apply.

Using service worker caching can help you extend the lifetime of prefetch resources beyond the five-minute window.

For example, Italian sports portal Virgilio Sport uses service workers to prefetch the most popular posts in their home page. They also use the Network Information API to avoid prefetching for users that are on a 2G connection.

As a result of this, over 3 weeks of observation Virgilio Sport witnessed load times for navigation to articles improve 78%, and the number of article impressions increase 45%.

Implement precaching with Workbox #

In the following section we'll use Workbox to show how to implement different caching techniques in the service worker that can be used as a complement to <link rel="prefetch">, or even a replacement for it, by delegating this task completely to the service worker.

1. Precache static pages and page subresources #

Precaching is the ability of the service worker to save files to the cache while it's installing.

In the following cases precaching is used to achieve a similar goal as prefetching: making navigations faster.

Precaching static pages #

For pages that are generated at build time (e.g. about.html, contact.html), or in completely static sites, one can just add the site's documents to the precache list, so they are already available in the cache every time the user accesses them:

workbox.precaching.precacheAndRoute([
  {url: '/about.html', revision: 'abcd1234'},
  // ... other entries ...
]);

Precaching page subresources #

Precaching static assets that the different sections of the site might use (e.g. JavaScript, CSS, etc.), is a general best practice and can give an extra boost in prefetching scenarios.

To speed up navigations in an e-commerce site, you can use <link rel="prefetch"> tags in listing pages to prefetch product detail pages for the first few products of a listing page. If you have already precached the product page subresources, this can make the navigation even faster.

To implement this:

Add a <link rel="prefetch"> tag to the page:

 <link rel="prefetch" href="/phones/smartphone-5x.html" as="document">

Add the page subresources to the precache list in the service worker:

workbox.precaching.precacheAndRoute([
  '/styles/product-page.ac29.css',
  // ... other entries ...
]);

2. Extend the lifetime of prefetch resources #

As mentioned earlier, <link rel="prefetch"> fetches and keeps resources in the HTTP cache for a limited amount of time, after which point the Cache-Control rules for a resource apply. As of Chrome 85, this value is 5 minutes.

Service workers allow you to extend the lifetime of the prefetch pages, while providing the added benefit of making those resources available for offline usage.

In the previous example, one could complement the <link rel="prefetch"> used to prefetch a product page with a Workbox runtime caching strategy.

To implement that:

Add a <link rel="prefetch"> tag to the page:

 <link rel="prefetch" href="/phones/smartphone-5x.html" as="document">

Implement a runtime caching strategy in the service worker for these types of requests:

new workbox.strategies.StaleWhileRevalidate({
  cacheName: 'document-cache',
  plugins: [
    new workbox.expiration.Plugin({
      maxAgeSeconds: 30 * 24 * 60 * 60, // 30 Days
    }),
  ],
});

In this case, we have opted to use a stale-while-revalidate strategy. In this strategy, pages can be requested from both the cache and the network, in parallel. The response comes from the cache if available, otherwise from the network. The cache is always kept up to date with the network response with each successful request.

3. Delegate prefetching to the service worker #

In most cases the best approach is to use <link rel="prefetch">. The tag is a resource hint designed to make prefetching as efficient as possible.

In some cases, though, it might be better to delegate this task completely to the service worker. For example: to prefetch the first few products in a client-side rendered product listing page, one might need to inject several <link rel="prefetch"> tags dynamically in the page, based on an API response. This can momentarily consume time on the page's main thread and make the implementation more difficult.

In cases like this, use a "page to service worker communication strategy", to delegate the task of prefetching completely to the service worker. This type of communication can be achieved by using worker.postMessage():

The Workbox Window package simplifies this type of communication, abstracting many details of the underlying call being done.

Prefetching with Workbox Window can be implemented in the following way:

In the page: call the service worker passing it the type of message, and the list of URLs to prefetch:

const wb = new Workbox('/sw.js');
wb.register();

const prefetchResponse = await wb.messageSW({type: 'PREFETCH_URLS', urls: […]});

In the service worker: implement a message handler to issue a fetch() request for each URL to prefetch:

addEventListener('message', (event) => {
  if (event.data.type === 'PREFETCH_URLS') {
    // Fetch URLs and store them in the cache
  }
});

Resilient search experiences

2020-06-23T00:00:00Z

Even in locations with fast networks a user might lose connection or connect to a flaky network, at some moments of the day. For example: a user is on the subway searching on the phone for a product on an e-commerce website. They type the product name, click the "search" button, and while waiting for the results, the connection is lost, leading to the standard browser offline page.

As a result, unless the user decides to come back to the site later, and repeat the same task, the site might lose a potential transaction and customer.

To provide a more resilient search experience in these cases you can use the Background Sync API, which persists failed queries so they can be retried once the connection is recovered. This technique, in combination with Web Push Notifications lets you inform the user of the search results, allowing you to keep them engaged with your service.

Production case #

For concrete application of this technique let's take a look at Google Search for Chrome in Android. When visiting the Google Search web app and going offline, instead of showing the standard network error page, the site serves a custom offline response, but allows users to enter their search query immediately. The page also prompts the user to opt-in for notifications, to receive a link to the search results page once the connection is recovered.

When the user performs a search, the service worker allows the query to be deferred and sent to Google's servers as soon as the device goes back online by using the Background Sync API, and to inform the user of the result by using the Push API.

Service workers allow Google Search to provide a meaningful offline experience and keep the user engaged, letting them complete their task.

Implement resilient search experiences with Workbox #

While Google Search implements this functionality without using Workbox, the Workbox library makes it easier by providing a Background Sync module, which takes care of many implementation details for us.

To implement a resilient search experience in Workbox, first, import the following modules in your service worker:

import {BackgroundSyncPlugin} from 'workbox-background-sync';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

Next, create an instance of the workbox.backgroundSync plugin, to automatically add failed requests to a queue, so they can be retried later:

const bgSyncPlugin = new workbox.backgroundSync.Plugin('offlineQueryQueue', {
  maxRetentionTime: 60,
  onSync: async ({queue}) => {
    let entry;
    while ((entry = await queue.shiftRequest())) {
      try {
        const response = await fetch(entry.request);
        const cache = await caches.open('offline-search-responses');
        const offlineUrl = `${entry.request.url}&notification=true`;
        cache.put(offlineUrl, response);
        showNotification(offlineUrl);
      } catch (error) {
        await this.unshiftRequest(entry);
        throw error;
      }
    }
  },
});

The plugin receives the following parameters:

offlineQueryQueue: The name of the queue that will be used to persist the failed requests in IndexedDB.
maxRetentionTime: The amount of time in minutes a request may be retried, after which point they will be discarded.
onSync: The callback that will be triggered when the connection is recovered. At that point, each failed request can be dequeued and processed, by calling queue.shiftRequest().

Finally, define a networkOnly runtime caching strategy for requests to the search URL (e.g. /search_action) and pass it the bgSyncPlugin defined previously:

workbox.routing.registerRoute(
  matchSearchUrl,
  new workbox.strategies.NetworkOnly({
        plugins: [bgSyncPlugin]
  })
);

This tells Workbox to always go to the network when the service worker intercepts a request for the search endpoint, and to delegate to the Background Sync plugin the task of managing offline scenarios.

As a result, when the user goes offline while searching, the query is automatically saved. When the connection is recovered the offline logic is triggered to process the request and inform the user of the result.

Conclusion #

In this article you learned how to implement a search experience capable of responding gracefully to offline scenarios, by combining the Background Sync API and the Push API. We used Workbox to show how to implement this feature, as it simplifies the process, but the same can be achieved by writing vanilla service worker code.

In the code samples we focused on the core part of the feature: how requests are intercepted and managed by the service worker. For a step-by-step guide on how to implement this functionality, including the offline page and the notification logic, check out the codelab at the end of this article.

Building resilient search experiences with Workbox

2020-06-23T00:00:00Z

This codelab shows you how to implement a resilient search experience with Workbox. The demo app it uses contains a search box that calls a server endpoint, and redirects the user to a basic HTML page.

Measure #

Before adding optimizations, it's always a good idea to first analyze the current state of the application.

Click Remix to Edit to make the project editable.
To preview the site, press View App. Then press Fullscreen .

In the new tab that just opened, check how the website behaves when going offline:

Press `Control+Shift+J` (or `Command+Option+J` on Mac) to open DevTools.
Click the Network tab.
Open Chrome DevTools and select the Network panel.
In the Throttling drop-down list, select Offline.
In the demo app enter a search query, then click the Search button.

The standard browser error page is shown:

Provide a fallback response #

The service worker contains the code to add the offline page to the precache list, so it can always be cached at the service worker install event.

Usually you would need to instruct Workbox to add this file to the precache list at build time, by integrating the library with your build tool of choice (e.g. webpack or gulp).

For simplicity, we've already done it for you. The following code at public/sw.js does that:

const FALLBACK_HTML_URL = '/index_offline.html';
…
workbox.precaching.precacheAndRoute([FALLBACK_HTML_URL]);

Next, add code to use the offline page as a fallback response:

To view the source, press View Source.
Add the following code to the bottom of public/sw.js:

workbox.routing.setDefaultHandler(new workbox.strategies.NetworkOnly());

workbox.routing.setCatchHandler(({event}) => {
  switch (event.request.destination) {
    case 'document':
      return caches.match(FALLBACK_HTML_URL);
      break;
    default:
      return Response.error();
  }
});

The code does the following:

Defines a default Network Only strategy that will apply to all requests.
Declares a global error handler, by calling workbox.routing.setCatchHandler() to manage failed requests. When requests are for documents, a fallback offline HTML page will be returned.

To test this functionality:

Go back to the other tab that is running your app.
Set the Throttling drop-down list back to Online.
Press Chrome's Back button to navigate back to the search page.
Make sure that the Disable cache checkbox in DevTools is disabled.
Long-press Chrome's Reload button and select Empty cache and hard reload to ensure that your service worker is updated.
Set the Throttling drop-down list back to Offline again.
Enter a search query, and click the Search button again.

The fallback HTML page is shown:

Request notification permission #

For simplicity, the offline page at views/index_offline.html already contains the code to request notification permissions in a script block at the bottom:

function requestNotificationPermission(event) {
  event.preventDefault();

  Notification.requestPermission().then(function (result) {
    showOfflineText(result);
  });
}

The code does the following:

When the user clicks subscribe to notifications the requestNotificationPermission() function is called, which calls Notification.requestPermission(), to show the default browser permission prompt. The promise resolves with the permission picked by the user, which can be either granted, denied, or default.
Passes the resolved permission to showOfflineText() to show the appropriate text to the user.

Persist offline queries and retry when back online #

Next, implement Workbox Background Sync to persist offline queries, so they can be retried when the browser detects that connectivity has returned.

Open public/sw.js for edit.
Add the following code at the end of the file:

const bgSyncPlugin = new workbox.backgroundSync.Plugin('offlineQueryQueue', {
  maxRetentionTime: 60,
  onSync: async ({queue}) => {
    let entry;
    while ((entry = await queue.shiftRequest())) {
      try {
        const response = await fetch(entry.request);
        const cache = await caches.open('offline-search-responses');
        const offlineUrl = `${entry.request.url}&notification=true`;
        cache.put(offlineUrl, response);
        showNotification(offlineUrl);
      } catch (error) {
        await this.unshiftRequest(entry);
        throw error;
      }
    }
  },
});

The code does the following:

workbox.backgroundSync.Plugin contains the logic to add failed requests to a queue so they can be retried later. These requests will be persisted in IndexedDB.
maxRetentionTime indicates the amount of time a request may be retried. In this case we have chosen 60 minutes (after which it will be discarded).
onSync is the most important part of this code. This callback will be called when connection is back so that queued requests are retrieved and then fetched from the network.
The network response is added to the offline-search-responses cache, appending the &notification=true query param, so that this cache entry can be picked up when a user clicks on the notification.

To integrate background sync with your service, define a NetworkOnly strategy for requests to the search URL (/search_action) and pass the previously defined bgSyncPlugin. Add the following code to the bottom of public/sw.js:

const matchSearchUrl = ({url}) => {
  const notificationParam = url.searchParams.get('notification');
  return url.pathname === '/search_action' && !(notificationParam === 'true');
};

workbox.routing.registerRoute(
  matchSearchUrl,
  new workbox.strategies.NetworkOnly({
    plugins: [bgSyncPlugin],
  }),
);

This tells Workbox to always go to the network, and, when requests fail, use the background sync logic.

Next, add the following code to the bottom of public/sw.js to define a caching strategy for requests coming from notifications. Use a CacheFirst strategy, so they can be served from the cache.

const matchNotificationUrl = ({url}) => {
  const notificationParam = url.searchParams.get('notification');
  return (url.pathname === '/search_action' && (notificationParam === 'true'));
};

workbox.routing.registerRoute(matchNotificationUrl,
  new workbox.strategies.CacheFirst({
     cacheName: 'offline-search-responses',
  })
);

Finally, add the code to show notifications:

function showNotification(notificationUrl) {
  if (Notification.permission) {
     self.registration.showNotification('Your search is ready!', {
        body: 'Click to see you search result',
        icon: '/img/workbox.jpg',
        data: {
           url: notificationUrl
        }
     });
  }
}

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  event.waitUntil(
     clients.openWindow(event.notification.data.url)
  );
});

Test the feature #

Go back to the other tab that is running your app.
Set the Throttling drop-down list back to Online.
Press Chrome's Back button to navigate back to the search page.
Long-press Chrome's Reload button and select Empty cache and hard reload to ensure that your service worker is updated.
Set the Throttling drop-down list back to Offline again.
Enter a search query, and click the Search button again.
Click subscribe to notifications.
When Chrome asks you if you want to grant the app permission to send notifications, click Allow.
Enter another search query and click the Search button again.
Set the Throttling drop-down list back to Online again.

Once the connection is back a notification will be shown:

Conclusion #

Workbox provides many built-in features to make your PWAs more resilient and engaging. In this codelab you have explored how to implement the Background Sync API by way of the Workbox abstraction, to ensure that offline user queries are not lost, and can be retried once connection is back. The demo is a simple search app, but you can use a similar implementation for more complex scenarios and use cases, including chat apps, posting messages on a social network, etc.

Preparing for AppCache removal

2020-05-18T00:00:00Z

Following up on previous announcements, support for AppCache will be removed from Chrome and other Chromium-based browsers. We encourage developers to migrate off of AppCache now, rather than waiting any longer.

Service workers, which are widely supported in current browsers, offer an alternative to providing the offline experience that AppCache had offered. See Migration strategies.

Timeline #

Recent changes to the Chrome release schedule means that the timing of some of these steps may vary. We will attempt to keep this timeline up-to-date, but at this point, please migrate off of AppCache as soon as possible, instead of waiting for specific milestones.

A "deprecated" feature still exists, but logs warning messages discouraging use. A "removed" feature no longer exists in the browser.

Deprecation in non-secure contexts	Chrome 50 (April 2016)
Removal from non-secure contexts	Chrome 70 (October 2018)
Deprecation in secure contexts	Chrome 79 (December 2019)
AppCache scope restriction	Chrome 80 (February 2020)
"Reverse" origin trial begins	Chrome 84 (July 2020)
Removal from secure contexts, except for those opted-in to the origin trial	Chrome 85 (August 2020)
Complete removal from secure contexts for everyone, with completion of origin trial	October 5th, 2021 (roughly Chrome 95)

Origin trial #

The timeline lists two upcoming milestones for removal. Beginning with Chrome 85, AppCache will no longer be available in Chrome by default. Developers who require additional time to migrate off of AppCache can sign up for a "reverse" origin trial to extend the availability of AppCache for their web apps. The origin trial will start in Chrome 84 (in advance of the default removal in Chrome 85), and will be active through October 5th, 2021 (roughly Chrome 95). At that point, AppCache will be fully removed for everyone, even those who had signed up for the origin trial.

To participate in the "reverse" origin trial:

Request a token for your origin.
Add the token to your HTML pages. There are two ways to do that:
- Add an origin-trial <meta> tag to the head of each page. For example: <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
- Alternatively, configure your server to return responses containing the Origin-Trial HTTP header. The resulting response header should look something like: Origin-Trial: TOKEN_GOES_HERE
Add the same token to your AppCache manifests. Do this via a new field in your manifest, with the format:
```
ORIGIN-TRIAL:
TOKEN_GOES_HERE
```
(There needs to be a new line between ORIGIN-TRIAL and your token.)

You can see a sample project embedded below that demonstrates adding the correct origin trial tokens into both the index.html and manifest.appcache files.

Why are tokens needed in multiple places? #

The same origin trial token needs to be associated with:

All of your HTML pages that use AppCache.
All of your AppCache manifests via the ORIGIN-TRIAL manifest field.

If you've participated in origin trials in the past, you might have added the token just to your HTML pages. The AppCache "reverse" origin trial is special in that you need to associate a token with each of your AppCache manifests as well.

Adding the origin trial token to your HTML pages enables the window.applicationCache interface from within your web apps. Pages that are not associated with a token won't be able to use window.applicationCache methods and events. Pages without a token also won't be able to load resources from the AppCache. Starting with Chrome 85, they will behave as if AppCache did not exist.

Adding the origin trial token to your AppCache manifests indicates that each manifest is still valid. Starting with Chrome 85, any manifests that does not have an ORIGIN-TRIAL field will be treated as malformed, and the rules within the manifest will be ignored.

Origin trial deployment timing and logistics #

While the "reverse" origin trial officially starts with Chrome 84, you can sign up for the origin trial today and add the tokens to your HTML and AppCache manifests. As your web app's audience gradually upgrades to Chrome 84, any tokens that you've already added will go into effect.

Once you've added a token to your AppCache manifest, visit about://appcache-internals to confirm that your local instance of Chrome (version 84 or later) has properly associated the origin trial token with your manifest's cached entries. If your origin trial is recognized, you should see a field with Token Expires: Tue Apr 06 2021... on that page, associated with your manifest:

Testing prior to removal #

We strongly encourage you to migrate off of AppCache as soon as is feasible. If you want to test removal of AppCache on your web apps, use the about://flags/#app-cache flag to simulate its removal. This flag is available starting with Chrome 84.

Migration strategies #

Service workers, which are widely supported in current browsers, offer an alternative to the offline experience provided by AppCache.

We've provided a polyfill that uses a service worker to replicate some of the functionality of AppCache, though it does not replicate the entire AppCache interface. In particular, it does not provide a replacement for the window.applicationCache interface or the related AppCache events.

For more complex cases, libraries like Workbox provide an easy way to create a modern service worker for your web app.

Service workers and AppCache are mutually exclusive #

While working on your migration strategy, please keep in mind that Chrome will disable AppCache functionality on any page that's loaded under the control of a service worker. In other words, as soon as you deploy a service worker that controls a given page, you're no longer able to use AppCache on that page.

Because of this, we recommend that you do not attempt to migrate to service workers piece-by-piece. It would be a mistake to deploy a service worker that only contains some of your caching logic. You cannot fall back on AppCache to "fill in the gaps."

Similarly, if you deploy a service worker prior to AppCache removal, and then discover that you need to roll back to your previous AppCache implementation, you need to ensure that you unregister that service worker. As long as there's a registered service worker in scope for a given page, AppCache will not be used.

The cross-platform story #

We encourage you to follow up with a specific browser vendor if you'd like more information about their plans for AppCache removal.

Firefox on all platforms #

Firefox deprecated AppCache in release 44 (September 2015), and has removed support for it in its Beta and Nightly builds as of September 2019.

Safari on iOS and macOS #

Safari deprecated AppCache in early 2018.

Chrome on iOS #

Chrome for iOS is a special case, as it uses a different browser engine than Chrome on other platforms: the WKWebView. Service workers are not currently supported in iOS apps using WKWebView, and Chrome's AppCache removal announcement does not cover the availability of AppCache on Chrome for iOS. Please keep this in mind if you know that your web app has a significant Chrome for iOS audience.

Android WebViews #

Some developers of Android applications use Chrome WebView to display web content, and might also use AppCache. However, it's not possible to enable an origin trial for a WebView. In light of that, Chrome WebView will support AppCache without an origin trial until the final removal takes place, expected in Chrome 90.

Learn more #

Here are some resources for developers migrating from AppCache to service workers.

Articles #

Tools #

Getting help #

If you run into an issue using a specific tool, open an issue in its GitHub repository.

You can ask a general question about migrating off of AppCache on Stack Overflow, using the tag html5-appcache.

If you encounter a bug related to Chrome's AppCache removal, please report it using the Chromium issue tracker.

Hero image based on Smithsonian Institution Archives, Acc. 11-007, Box 020, Image No. MNH-4477.

Integrate PWAs into built-in sharing UIs with Workbox

2019-12-19T00:00:00Z

The Web Share Target API lets you display your Progressive Web App in a user's system-level share sheet after it's been installed. While it works great if you have a server available to receive the request, it's much harder to get working if you don't.

In this article we'll use Workbox, a set of JavaScript libraries for adding offline support to web apps, to create a share target URL that lives entirely inside your service worker. This lets static sites and single-page apps serve as share targets without a dedicated server endpoint.

System-level share target picker with an installed PWA called Share Target Test as an option.

On the same page #

If you're unfamiliar with how Web Share Target Works, Receiving shared data with the Web Share Target API gives you an in-depth introduction. Here's a quick review.

There are two parts to implementing web share target functionality. First, update your web app manifest to indicate that you want your app to be a share target when installed. The following example directs shares to the /share url via a POST request. It is encoded as a multipart form, with title being called name, text being called description, and JPEG images being called photos.

…
"share_target": {
  "action": "/share",
  "method": "POST",
  "enctype": "multipart/form-data",
  "params": {
    "title": "name",
    "text": "description",
    "files": [
      {
        "name": "photos",
        "accept": ["image/jpeg", ".jpg"]
      }
    ]
  }
}
…

While normally handled by a server endpoint, a neat trick you can do for a share target is to register a route directly in your service worker to handle the request. This will let your app be a share target without a backend.

You do this in Workbox by registering a route that's handled by your service worker. Start by importing registerRoute from 'workbox-routing'. Notice that it's registered for the /share route, the same one listed in the example web app manifest. In response it calls shareTargetHandler().

import { registerRoute } from 'workbox-routing';

registerRoute(
  '/share',
  shareTargetHandler,
  'POST'
);

The shareTargetHandler() function is asynchronous and takes the event, awaits the form data, then retrieves the media files from that.

async function shareTargetHandler ({event}) {
  const formData = await event.request.formData();
  const mediaFiles = formData.getAll('media');

  for (const mediaFile of mediaFiles) {
    // Do something with mediaFile
    // Maybe cache it or post it back to a server
  });

  // Do something with the rest of formData as you need
  // Maybe save it to IndexedDB
};

You can then do whatever you'd like with these files. You can cache them. You can send them somewhere with a fetch request. You can even use the other manifest options, maybe serving a page with some query parameters for the other shared items or storing the data and pointers to the media in the Cache Storage API or IndexedDB.

You can try it out on the sample app Fugu Journal and see its service worker implementation in its source code.

One common thing you might do is hold shared resources until better network connections are available. Workbox also supports periodic background sync.

Conclusion #

The Share Target API is a simple way to deeply integrate your Progressive Web App into user's devices, putting them on-par with platform-specific applications for the critical task of sharing content between apps. But doing so usually requires a server available to receive the request. By leveraging Workbox to create a share target route directly in your service worker, your app is free of this constraint, allowing Share Target to work for apps while offline and without backends.

Photo by Elaine Casap on Unsplash

Keeping things fresh with stale-while-revalidate

2019-07-18T00:00:00Z

What shipped? #

stale-while-revalidate helps developers balance between immediacy—loading cached content right away—and freshness—ensuring updates to the cached content are used in the future. If you maintain a third-party web service or library that updates on a regular schedule, or your first-party assets tend to have short lifetimes, then stale-while-revalidate may be a useful addition to your existing caching policies.

Support for setting stale-while-revalidate alongside max-age in your Cache-Control response header is available in Chrome 75 and Firefox 68.

Browsers that don't support stale-while-revalidate will silently ignore that configuration value, and use max-age, as I'll explain shortly…

What's it mean? #

Let's break down stale-while-revalidate into two parts: the idea that a cached response might be stale, and the process of revalidation.

First, how does the browser know whether a cached response is "stale"? A Cache-Control response header that contains stale-while-revalidate should also contain max-age, and the number of seconds specified via max-age is what determines staleness. Any cached response newer than max-age is considered fresh, and older cached responses are stale.

If the locally cached response is still fresh, then it can be used as-is to fulfill a browser's request. From the perspective of stale-while-revalidate, there's nothing to do in this scenario.

But if the cached response is stale, then another age-based check is performed: is the age of the cached response within the additional time window provided by the stale-while-revalidate setting?

If the age of a stale response falls into this window, then it will be used to fulfill the browser's request. At the same time, a "revalidation" request will be made against the network in a way that doesn't delay the use of the cached response. The returned response might contain the same information as the previously cached response, or it might be different. Either way, the network response is stored locally, replacing whatever was previously cache, and resetting the "freshness" timer used during any future max-age comparisons.

However, if the stale cached response is old enough that it falls outside the stale-while-revalidate window of time, then it will not fulfill the browser's request. The browser will instead retrieve a response from the network, and use that for both fulfilling the initial request and also populating the local cache with a fresh response.

Live Example #

Below is a simple example of an HTTP API for returning the current time—more specifically, the current number of minutes past the hour.

In this scenario, the web server uses this Cache-Control header in its HTTP response:

Cache-Control: max-age=1, stale-while-revalidate=59

This setting means that, if a request for the time is repeated within the next 1 second, the previously cached value will still be fresh, and used as-is, without any revalidation.

If a request is repeated between 1 and 60 seconds later, then the cached value will be stale, but will be used to fulfill the API request. At the same time, "in the background," a revalidation request will be made to populate the cache with a fresh value for future use.

If a request is repeated after more than 60 seconds, then the stale response isn't used at all, and both fulfilling the browser's request and the cache revalidation will depend on getting a response back from the network.

Here's a breakdown of those three distinct states, along with the window of time in which each of them apply for our example:

What are the common use cases? #

While the above example for a "minutes after the hour" API service is contrived, it illustrates the expected use case—services that provide information which needs to be refreshed, but where some degree of staleness is acceptable.

Less contrived examples might be an API for the current weather conditions, or the top news headlines that were written in the past hour.

Generally, any response that updates at a known interval, is likely to be requested multiple times, and is static within that interval is a good candidate for short-term caching via max-age. Using stale-while-revalidate in addition to max-age increases the likelihood that future requests can be fulfilled from the cache with fresher content, without blocking on a network response.

How does it interact with service workers? #

If you've heard of stale-while-revalidate chances are that it was in the context of recipes used within a service worker.

Using stale-while-revalidate via a Cache-Control header shares some similarities with its use in a service worker, and many of the same considerations around freshness trade-offs and maximum lifetimes apply. However, there are a few considerations that you should take into account when deciding whether to implement a service worker-based approach, or just rely on the Cache-Control header configuration.

Use a service worker approach if… #

You're already using a service worker in your web app.
You need fine-grained control over the contents of your caches, and want to implement something like a least-recently used expiration policy. Workbox's Cache Expiration module can help with this.
You want to be notified when a stale response changes in the background during the revalidation step. Workbox's Broadcast Cache Update module can help with this.
You need this stale-while-revalidate behavior in all modern browsers.

Use a Cache-Control approach if… #

You would rather not deal with the overhead of deploying and maintaining a service worker for your web app.
You are fine with letting the browser's automatic cache management prevent your local caches from growing too large.
You are fine with an approach that is not currently supported in all modern browsers (as of July 2019; support may grow in the future).

If you're using a service worker and also have stale-while-revalidate enabled for some responses via a Cache-Control header, then the service worker will, in general, have "first crack" at responding to a request. If the service worker decides not to respond, or if in the process of generating a response it makes a network request using fetch(), then the behavior configured via the Cache-Control header will end up going into effect.

Learn more #

stale-while-revalidate response in the Fetch API spec.
RFC 5861, covering the initial stale-while-revalidate specification.
The HTTP cache: your first line of defense, from the "Network reliability" guide on this site.

Hero image by Samuel Zeller.

Bringing service workers to Google Search

2019-06-20T00:00:00Z

Background #

Search for just about any topic on Google, and you're presented with an instantly recognizable page of meaningful, relevant results. What you probably didn't realize is that this search results page is, under certain scenarios, served by a powerful piece of web technology called a service worker.

Rolling out service worker support for Google Search without negatively impacting the performance required dozens of engineers working across multiple teams. This is the story of what shipped, how performance was measured, and what tradeoffs were made.

Key reasons for exploring service workers #

Adding a service worker to a web app, just like making any architectural change to your site, should be done with a clear set of goals in mind. For the Google Search team, there were a few key reasons why adding a service worker was worth exploring.

Limited search result caching #

The Google Search team found that it's common for users to search for the same terms more than once within a short period of time. Rather than trigger a new backend request just to get what's likely to be the same results, the Search team wanted to take advantage of caching and fulfill those repeat requests locally.

The importance of freshness can't be discounted, and sometimes users search for the same terms repeatedly because it's an evolving topic, and they expect to see fresh results. Using a service worker allows the Search team to implement fine-grained logic to control the lifetime of locally cached search results, and achieve the exact balance of speed vs. freshness that they believe best serves users.

Meaningful offline experience #

Additionally, the Google Search team wanted to provide a meaningful offline experience. When a user wants to find out about a topic, they want to go straight to the Google Search page and start searching, without worrying about an active Internet connection.

Without a service worker, visiting the Google search page while offline would just lead to the browser's standard network error page, and users would have to remember to come back and try again once their connection returned. With a service worker, it's possible to serve a custom offline HTML response, and allow users to enter their search query immediately.

The results won't be available until there's an Internet connection, but the service worker allows the search to be deferred and sent to Google's servers as soon as the device goes back online using the background sync API.

Smarter JavaScript caching and serving #

Another motivation was to optimize the caching and loading of the modularized JavaScript code that powers the various types of features on the search results page. There are a number of benefits offered by JavaScript bundling that make sense when there's no service worker involvement, so the Search team did not want to simply stop bundling entirely.

By using a service worker's ability to version and cache fine-grained chunks of JavaScript at runtime, the Search team suspected that they could reduce the amount of cache churn and ensure that JavaScript reused in the future can be cached efficiently. The logic inside of their service worker can analyze an outgoing HTTP request for a bundle that contains multiple JavaScript modules, and fulfill it by piecing together multiple, locally cached modules—effectively "unbundling" when possible. This saves user bandwidth, and improves overall responsiveness.

There are also performance benefits of using cached JavaScript served by a service worker: in Chrome, a parsed, byte code representation of that JavaScript is stored and reused, leading to less work that needs to be done at runtime in order to execute the JavaScript on the page.

Challenges and solutions #

Here are a few of the hurdles that needed to be overcome in order to achieve the team's stated goals. While some of these challenges are specific to Google Search, many of them are applicable to a wide range of sites that might be considering a service worker deployment.

Problem: service worker overhead #

The biggest challenge, and the one true blocker for launching a service worker on Google Search, was to ensure that it did not do anything that might increase user-perceived latency. Google Search takes performance very seriously, and in the past, has blocked launches of new functionality if it contributed even tens of milliseconds of additional latency for a given user population.

When the team started collecting performance data during their earliest experiments, it became obvious that there would be a problem. The HTML returned in response to navigation requests for the search result page is dynamic, and varies greatly depending on logic that needs to run on Search's web servers. There's currently no way for the service worker to replicate this logic and return cached HTML immediately—the best it could do is to pass along navigation requests to the backend web servers, which necessitates a network request.

Without a service worker, this network request happens immediately upon user navigation. When a service worker is registered, it always needs to be started up and given a chance to execute its fetch event handlers, even when there's no chance those fetch handlers will do anything other than go to the network. The amount of time that it takes to start up and run the service worker code is pure overhead added on top of every navigation:

This puts the service worker implementation at too much of a latency disadvantage to justify any other benefits. Additionally, the team found that, based on measuring service worker boot times on real-world devices, there was a wide distribution of startup times, with some low-end mobile devices taking almost as much time to start up the service worker as it might take to make the network request for the results page's HTML.

The single, most crucial feature that allowed the Google Search team to move ahead with their service worker launch is navigation preload. Using navigation preload is a key performance win for any service worker that needs to use a response from the network to satisfy navigation requests. It provides a hint to the browser to start making the navigation request immediately, at the same time as the service worker starts up:

As long as the amount of time it takes for the service worker to start up is less than the amount of time it takes to get a response back from the network, there shouldn't be any latency overhead introduced by the service worker.

The Search team also needed to avoid using a service worker on low-end mobile devices where the service worker boot time could exceed the navigation request. Since there's no hard-and-fast rule for what constitutes a "low-end" device, they came up with the heuristic of checking the total RAM installed on the device. Anything less than 2 gigabytes of memory fell into their low-end device category, where service worker startup time would be unacceptable.

Available storage space is another consideration, since the full set of resources to be cached for future use can run to several megabytes. The navigator.storage interface allows the Google Search page to figure out in advance whether their attempts to cache data run the risk of failing due to storage quota failures.

This left the Search team with multiple pieces of criteria that they could use to determine whether or not to use a service worker: if a user comes to the Google Search page using a browser that supports navigation preload, and has at least 2 gigabytes of RAM, and enough free storage space, then a service worker is registered. Browsers or devices that don't meet that criteria won't end up with a service worker, but they'll still see the same Google Search experience as they always have.

One side benefit of this selective registration is the ability to ship a smaller, more efficient service worker. Targeting fairly modern browsers to run the service worker code eliminates the overhead of transpilation and polyfills for older browsers. This ended up cutting out around 8 kilobytes of uncompressed JavaScript code from the total size of the service worker's implementation.

Problem: service worker scopes #

Once the Search team ran enough latency experiments and were confident that using navigation preload offered them a viable, latency-neutral path for using a service worker, some practical issues started moving to the forefront. One of those issues has to do with service worker's scoping rules. A service worker's scope determines which pages it can potentially take control of.

Scoping works based on the URL path prefix. For domains that host a single web app, this isn't an issue, as you'd normally just use a service worker with the maximal scope of /, which could take control of any page under the domain. But Google Search's URL structure is a little more complicated.

If the service worker were given the maximal scope of /, it would end up being able to take control of any page hosted under www.google.com (or the regional equivalent), and there are URLs under that domain that have nothing to do with Google Search. A more reasonable, restrictive scope would be /search, which at least would eliminate URLs completely unrelated to search results.

Unfortunately, even that /search URL path is shared amongst different flavor of Google Search results, with URL query parameters determining which specific type of search result is shown. Some of those flavors use completely different codebases than the traditional web search result page. For example, Image Search and Shopping Search are both served under the /search URL path with different query parameters, but neither of those interfaces were ready to ship their own service worker experience (yet).

Solution: create a dispatch and routing framework #

While there are some proposals that allow for something more powerful than URL path prefixes to determine service worker scopes, the Google Search team was stuck deploying a service worker that did nothing for a subset of pages it controlled.

To work around this, the Google Search team built up a bespoke dispatch and routing framework that could be configured to check for criteria like the query parameters of the client page, and use those to determine which specific code path to go down. Rather than hardcoding rules, the system was built to be flexible and allow teams that share the URL space, like Image Search and Shopping Search, to drop in their own service worker logic down the line, if they decide to implement it.

Problem: personalized results and metrics #

Users can sign in to Google Search using their Google Accounts, and their search results experience may be customized based on their particular account data. Logged in users are identified by specific browser cookies, which is a venerable and widely-supported standard.

One downside of using browser cookies, though, is that they are not exposed inside of a service worker, and there is no way of automatically examining their values and ensuring that they have not changed due to a user logging out or switching accounts. (There is effort underway to bring cookie access to service workers, but as of this writing, the approach is experimental and is not widely supported.)

A mismatch between the service worker's view of the current logged in user and the actual user logged in to the Google Search web interface could lead to incorrectly personalized search results or misattributed metrics and logging. Any of those failure scenarios would be a serious issue for the Google Search team.

Solution: send cookies using postMessage #

Rather than wait for experimental APIs to launch and provide direct access to the browser's cookies inside of a service worker, the Google Search team went with a stop-gap solution: whenever a page controlled by the service worker is loaded, the page reads the relevant cookies and uses postMessage() to send them to the service worker.

The service worker then checks the current cookie value against the value that it expects, and if there's a mismatch, it takes steps to purge any user-specific data from its storage, and reloads the search results page without any incorrect personalization.

The specific steps that the service worker takes to reset things to a baseline are particular to Google Search's requirements, but the same general approach may be useful to other developers who deal with personalized data keyed off of browsers cookies.

Problem: experiments and dynamism #

As mentioned, the Google Search team relies heavily on running experiments in production, and testing the effects of new code and features in the real world before turning them on by default. This can be a bit of a challenge with a static service worker that relies heavily on cached data, since opting users in and out of experiments often requires communication with the backend server.

Solution: dynamically generated service worker script #

The solution that the team went with was to use a dynamically generated service worker script, customized by the web server for each individual user, instead of a single, static service worker script that gets generated ahead of time. Information about experiments that might affect the service worker's behavior or network requests in general are included directly in this customized service worker scripts. Changing the sets of active experiences for a user is done via a combination of traditional techniques, like browser cookies, as well as serving updated code in the registered service worker URL.

Using a dynamically generated service worker script also makes it easier to provide an escape hatch in the unlikely event that a service worker implementation has a fatal bug that needs to be avoided. The dynamic server worker response could be a no-op implementation, effectively disabling the service worker for some or all of the current users.

Problem: coordinating updates #

One of the toughest challenges facing any real-world service worker deployment is to devise a reasonable tradeoff between avoiding the network in favor of the cache, while at the same time, ensuring that existing users get critical updates and changes soon after they're deployed to production. The right balance depends on a lot of factors:

Whether your web app is a long-lived single page app that a user keeps open indefinitely, without navigating to new pages.
What the deployment cadence is for updates to your backend web server.
Whether the average user would tolerate using a slightly out-of-date version of your web app, or whether freshness is the top priority.

While experimenting with service workers, the Google Search team made sure to keep the experiments running across a number of scheduled backend updates, to ensure that the metrics and user experience would more closely match what return users would end up seeing in the real-world.

Solution: balance freshness and cache-utilization #

After testing a number of different configuration options, the Google Search team found that the following setup provided the right balance between freshness and cache-utilization.

The service worker script URL is served with the Cache-Control: private, max-age=1500 (1500 seconds, or 25 minutes) response header, and is registered with updateViaCache set to 'all' to ensure that the header is honored. The Google Search web backend is, as you might imagine, a large, globally distributed set of servers that requires as close to 100% uptime as possible. Deploying a change that would affect the service worker script's contents is done in a rolling fashion.

If a user hits a backend that has been updated, and then quickly navigates to another page which hits a backend that hasn't yet received the updated service worker, they'd end up flip-flopping between versions multiple times. Therefore, telling the browser to only bother checking for an updated script if 25 minutes has passed since the last check does not have a significant downside. The upside of opting-in to this behavior is cutting down significantly on the traffic received by the endpoint that dynamically generates the service worker script.

Additionally, an ETag header is set on the service worker script's HTTP response, ensuring that when an update check is made after 25 minutes has passed, the server can respond efficiently with an HTTP 304 response if there haven't been any updates to the service worker deployed in the interim.

While some interactions within the Google Search web app use single page app-style navigations (i.e. via the History API), for the most part, Google Search is a traditional web app that uses "real" navigations. This comes into play when the team decided that it would be effective to use two options that accelerate the service worker update lifecycle: clients.claim() and skipWaiting(). Clicking around Google Search's interface generally ends up navigating to new HTML documents. Calling skipWaiting ensures that an updated service worker gets a chance to handle those new navigation requests immediately after installation. Similarly, calling clients.claim() means that the updated service worker gets a chance to start controlling any open Google Search pages that are uncontrolled, following service worker activation.

The approach that Google Search went with isn't necessarily a solution that works for everyone—it was the result of carefully A/B testing various combinations of serving options until they found what worked best for them. Developers whose backend infrastructure allow them to deploy updates more quickly might prefer that the browser check for an updated service worker script as frequently as possible, by always ignoring the HTTP cache. If you're building a single page app that users will might keep open for a long period of time, using skipWaiting() is probably not the right choice for you—you risk running into cache inconsistencies if you allow the new service worker to activate while there are long-lived clients.

Key Takeaways #

By default, service workers aren't performance neutral #

Adding a service worker to your web app means inserting an additional piece of JavaScript that needs to be loaded and executed before your web app gets responses to its requests. If those responses end up coming from a local cache rather than from the network, then the overhead of running the service worker is usually negligible in comparison to the performance win from going cache-first. But if you know that your service worker always has to consult the network when handling navigation requests, using navigation preload is a crucial performance win.

Service workers are (still!) a progressive enhancement #

The service worker support story is much brighter today than it was even a year ago. All modern browsers now feature at least some support for service workers, but unfortunately, there are some advanced service worker features—like background sync and navigation preload—that aren't rolled out universally. Feature checking for the specific subset of features that you know you need, and only registering a service worker when those are present, is still a reasonable approach to take.

Similarly, if you've run experiments in the wild, and know that low-end devices end up performing poorly with the additional overhead of a service worker, you can abstain from registering a service worker in those scenarios as well.

You should continue to treat service workers as a progressive enhancement that gets added to a web app when all the prerequisites are met and the service worker adds something positive to user experience and overall loading performance.

Measure everything #

The only way you can figure out whether shipping a service worker has had a positive or negative impact on your users' experiences is to experiment and measure the results.

The specifics of setting up meaningful measurements depends on what analytics provider you're using, and how you normally conduct experiments in your deployment setup. One approach, using Google Analytics to collect metrics, is detailed in this case study based on the experience using service workers in the Google I/O web app.

Non-goals #

While many in the web development community associate service workers with Progressive Web Apps, building a "Google Search PWA" was not an initial goal of the team. The Google Search web app doesn't currently provide metadata via a web app manifest, nor does it encourage users to go through the Add to Home Screen flow. The Search team is currently satisfied with users coming to their web app via the traditional entry points for Google Search.

Rather than trying to turn the Google Search web experience into the equivalent of what you'd expect from an installed application, the focus on the initial roll out was to progressively enhance the existing web site.

Acknowledgements #

Thanks to the entire Google Search web development team for their work on the service worker implementation, and for sharing the background material that went into writing this article. Particular thanks goes to Philippe Golle, Rajesh Jagannathan, R. Samuel Klatchko, Andy Martone, Leonardo Peña, Rachel Shearer, Greg Terrono, and Clay Woolam.

Update (Oct. 2021): Since this article was originally published, the Google Search team has reevaluated the benefits and tradeoffs of their current service worker architecture. The service worker described above is being retired. As the Google Search web infrastructure evolves, the team may revisit their service worker design.

Code splitting with React.lazy and Suspense

2019-04-29T00:00:00Z

The React.lazy method makes it easy to code-split a React application on a component level using dynamic imports.

import React, { lazy } from 'react';

const AvatarComponent = lazy(() => import('./AvatarComponent'));

const DetailsComponent = () => (
  <div>
    <AvatarComponent />
  </div>
)

Why is this useful? #

A large React application will usually consist of many components, utility methods, and third-party libraries. If an effort isn't made to try to load different parts of an application only when they're needed, a single, large bundle of JavaScript will be shipped to your users as soon as they load the first page. This can affect page performance significantly.

The React.lazy function provides a built-in way to separate components in an application into separate chunks of JavaScript with very little legwork. You can then take care of loading states when you couple it with the Suspense component.

Suspense #

The problem with shipping a large JavaScript payload to users is the length of time it would take for the page to finish loading, especially on weaker devices and network connections. This is why code splitting and lazy loading is extremely useful.

However, there will always be a slight delay that users have to experience when a code-split component is being fetched over the network, so it's important to display a useful loading state. Using React.lazy with the Suspense component helps solve this problem.

import React, { lazy, Suspense } from 'react';

const AvatarComponent = lazy(() => import('./AvatarComponent'));

const renderLoader = () => <p>Loading</p>;

const DetailsComponent = () => (
  <Suspense fallback={renderLoader()}>
    <AvatarComponent />
  </Suspense>
)

Suspense accepts a fallback component which allows you to display any React component as a loading state. The following example shows how this works. The avatar is only rendered when the button is clicked, where a request is then made to retrieve the code necessary for the suspended AvatarComponent. In the meantime, the fallback loading component is shown.

In here, the code that makes up AvatarComponent is small which is why the loading spinner only shows for a short amount of time. Larger components can take much longer to load, especially on weak network connections.

To better demonstrate how this works:

To preview the site, press View App. Then press Fullscreen .
Press `Control+Shift+J` (or `Command+Option+J` on Mac) to open DevTools.
Click the Network tab.
Click the Throttling dropdown, which is set to No throttling by default. Select Fast 3G.
Click the Click Me button in the app.

The loading indicator will show for longer now. Notice how all the code that makes up the AvatarComponent is fetched as a separate chunk.

Suspending multiple components #

Another feature of Suspense is that it allows you to suspend multiple components from loading, even if they are all lazy loaded.

For example:

import React, { lazy, Suspense } from 'react';

const AvatarComponent = lazy(() => import('./AvatarComponent'));
const InfoComponent = lazy(() => import('./InfoComponent'));
const MoreInfoComponent = lazy(() => import('./MoreInfoComponent'));

const renderLoader = () => <p>Loading</p>;

const DetailsComponent = () => (
  <Suspense fallback={renderLoader()}>
    <AvatarComponent />
    <InfoComponent />
    <MoreInfoComponent />
  </Suspense>
)

This is an extremely useful way to delay rendering of multiple components while only showing a single loading state. Once all the components have finished fetching, the user gets to see them all displayed at the same time.

You can see this with the following embed:

Without this, it's easy to run into the problem of staggered loading, or different parts of a UI loading one after the other with each having their own loading indicator. This can make the user experience feel more jarring.

Handle loading failures #

Suspense allows you to display a temporary loading state while network requests are made under the hood. But what if those network requests fail for some reason? You might be offline, or perhaps your web app is attempting to lazy-load a versioned URL that is out of date, and no longer available following a server redeployment.

React has a standard pattern for gracefully handling these types of loading failures: using an error boundary. As described in the documentation, any React component can serve as an error boundary if it implements either (or both) of the lifecycle methods static getDerivedStateFromError() or componentDidCatch().

To detect and handle lazy loading failures, you can wrap your Suspense component with a parent components that serves as an error boundary. Inside the error boundary's render() method, you can render the children as-is if there's no error, or render a custom error message if something goes wrong:

import React, { lazy, Suspense } from 'react';

const AvatarComponent = lazy(() => import('./AvatarComponent'));
const InfoComponent = lazy(() => import('./InfoComponent'));
const MoreInfoComponent = lazy(() => import('./MoreInfoComponent'));

const renderLoader = () => <p>Loading</p>;

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = {hasError: false};
  }

  static getDerivedStateFromError(error) {
    return {hasError: true};
  }

  render() {
    if (this.state.hasError) {
      return <p>Loading failed! Please reload.</p>;
    }

    return this.props.children;
  }
}

const DetailsComponent = () => (
  <ErrorBoundary>
    <Suspense fallback={renderLoader()}>
      <AvatarComponent />
      <InfoComponent />
      <MoreInfoComponent />
    </Suspense>
  </ErrorBoundary>
)

Conclusion #

If you are unsure where to begin applying code splitting to your React application, follow these steps:

Begin at the route level. Routes are the simplest way to identify points of your application that can be split. The React docs show how Suspense can be used along with react-router.
Identify any large components on a page on your site that only render on certain user interactions (like clicking a button). Splitting these components will minimize your JavaScript payloads.
Consider splitting anything else that is offscreen and not critical for the user.

What is network reliability and how do you measure it?

2018-11-05T00:00:00Z

The modern web is enjoyed by a wide swath of people, using a range of different devices and types of network connections. Your creations can reach users all across the world, but delivering a reliable experience on the web for all of your users can be challenging. It can be a challenge just to understand what reliability means.

Reliable while offline #

One way of thinking about reliability is whether your web app will work without a network connection. This is a type of reliability that users take for granted with platform-specific apps installed on a mobile device from an app store. When you see an icon for one of these apps, you expect to be able to tap on it and open up some sort of experience, regardless of whether you're currently connected to the Internet.

Until recently, it's been a challenge to build web applications that are reliable without a network connection.

Reliably fast #

Another way of thinking about reliability is whether your users can rely on your web app loading at a fast enough speed when they have a network connection that might be less than ideal. Will returning users have the same experience interacting with your web app when they're on a cellular connection as they do when they're on wi-fi? And what about users who have a high-latency, or "lie-fi" connection. Will your web app be reliably fast even in those scenarios?

It's not enough to be fast under the best circumstances. Your users will view your web app's performance through the lens of how it behaves in all network conditions.

Reliable is achievable #

The good news is that the modern web platform provides technologies—such as service workers and the Cache Storage API—that can serve as the building blocks for creating reliable web applications. They allow you to write code which sits between your web app and the network. In many cases, you can bypass the network entirely, and instead use previously cached content to fulfill your web app's requests.

Your guiding light: Responds with a 200 OK while offline #

Once you start building out a service worker and serving content from caches, it's hard to know if you're doing it effectively. How do you know that the service worker you implement really does help your web app avoid the network? How do you prevent a small change to your caching strategy from breaking your carefully crafted offline experience?

Lighthouse provides one specific test that is of particular interest when building a reliable web app: Responds with a 200 OK while offline:

What's actually being tested here? It boils down to simulating a loss of network connectivity within your browser, followed by an attempt to load whichever URL on your site is being audited. This tests one aspect of building a reliable site—being reliable while offline—using a controlled, repeatable sequence of actions.

It's a journey #

If you're just starting out, then there's a very good chance that you'll get back a negative result for the Responds with a 200 while offline check. That's okay! Unless you're using a customized starter project, web applications don't have that type of reliability by default. The next few guides will introduce the techniques you need to identify what your web app is loading, and teach you how to use Lighthouse to make that loading experience reliable.

Throughout this process, you're encouraged to keep re-running the Lighthouse audits. They serve as a guiding light throughout your journey, starting with a new web application and ending with a reliable progressive web app.

Prevent unnecessary network requests with the HTTP Cache

2018-11-05T00:00:00Z

Fetching resources over the network is both slow and expensive:

Large responses require many roundtrips between the browser and the server.
Your page won't load until all of its critical resources have downloaded completely.
If a person is accessing your site with a limited mobile data plan, every unnecessary network request is a waste of their money.

How can you avoid unnecessary network requests? The browser's HTTP Cache is your first line of defense. It's not necessarily the most powerful or flexible approach, and you have limited control over the lifetime of cached responses, but it's effective, it's supported in all browsers, and it doesn't require much work.

This guide shows you the basics of an effective HTTP caching implementation.

Browser compatibility #

There isn't actually a single API called the HTTP Cache. It's the general name for a collection of web platform APIs. Those APIs are supported in all browsers:

How the HTTP Cache works #

All HTTP requests that the browser makes are first routed to the browser cache to check whether there is a valid cached response that can be used to fulfill the request. If there's a match, the response is read from the cache, which eliminates both the network latency and the data costs that the transfer incurs.

The HTTP Cache's behavior is controlled by a combination of request headers and response headers. In an ideal scenario, you'll have control over both the code for your web application (which will determine the request headers) and your web server's configuration (which will determine the response headers).

Check out MDN's HTTP Caching article for a more in-depth conceptual overview.

Request headers: stick with the defaults (usually) #

While there are a number of important headers that should be included in your web app's outgoing requests, the browser almost always takes care of setting them on your behalf when it makes requests. Request headers that affect checking for freshness, like If-None-Match and If-Modified-Since just appear based on the browser's understanding of the current values in the HTTP Cache.

This is good news—it means that you can continue including tags like <img src="my-image.png"> in your HTML, and the browser automatically takes care of HTTP caching for you, without extra effort.

Response headers: configure your web server #

The part of the HTTP caching setup that matters the most is the headers that your web server adds to each outgoing response. The following headers all factor into effective caching behavior:

Cache-Control. The server can return a Cache-Control directive to specify how, and for how long, the browser and other intermediate caches should cache the individual response.
ETag. When the browser finds an expired cached response, it can send a small token (usually a hash of the file's contents) to the server to check if the file has changed. If the server returns the same token, then the file is the same, and there's no need to re-download it.
Last-Modified. This header serves the same purpose as ETag, but uses a time-based strategy to determine if a resource has changed, as opposed to the content-based strategy of ETag.

Some web servers have built-in support for setting those headers by default, while others leave the headers out entirely unless you explicitly configure them. The specific details of how to configure headers varies greatly depending on which web server you use, and you should consult your server's documentation to get the most accurate details.

To save you some searching, here are instructions on configuring a few popular web servers:

Leaving out the Cache-Control response header does not disable HTTP caching! Instead, browsers effectively guess what type of caching behavior makes the most sense for a given type of content. Chances are you want more control than that offers, so take the time to configure your response headers.

Which response header values should you use? #

There are two important scenarios that you should cover when configuring your web server's response headers.

Long-lived caching for versioned URLs #

How versioned URLs can help your caching strategy

Versioned URLs are a good practice because they make it easier to invalidate cached responses.

Suppose your server instructs browsers to cache a CSS file for 1 year (Cache-Control: max-age=31536000) but your designer just made an emergency update that you need to roll out immediately. How do you notify browsers to update the "stale" cached copy of the file? You can't, at least not without changing the URL of the resource. After the browser caches the response, the cached version is used until it's no longer fresh, as determined by max-age or expires, or until it is evicted from the cache for some other reason—for example, the user clearing their browser cache. As a result, different users might end up using different versions of the file when the page is constructed: users who just fetched the resource use the new version, while users who cached an earlier (but still valid) copy use an older version of its response. How do you get the best of both worlds: client-side caching and quick updates? You change the URL of the resource and force the user to download the new response whenever its content changes. Typically, you do this by embedding a fingerprint of the file, or a version number, in its filename—for example, style.x234dff.css.

When responding to requests for URLs that contain "fingerprint" or versioning information, and whose contents are never meant to change, add Cache-Control: max-age=31536000 to your responses.

Setting this value tells the browser that when it needs to load the same URL anytime over the next one year (31,536,000 seconds; the maximum supported value), it can immediately use the value in the HTTP Cache, without having to make a network request to your web server at all. That's great—you've immediately gained the reliability and speed that comes from avoiding the network!

Build tools like webpack can automate the process of assigning hash fingerprints to your asset URLs.

Server revalidation for unversioned URLs #

Unfortunately, not all of the URLs you load are versioned. Maybe you're not able to include a build step prior to deploying your web app, so you can't add hashes to your asset URLs. And every web application needs HTML files—those files are (almost!) never going to include versioning information, since no one will bother to use your web app if they need to remember that the URL to visit is https://example.com/index.34def12.html. So what can you do for those URLs?

This is one scenario in which you need to admit defeat. HTTP caching alone isn't powerful enough to avoid the network completely. (Don't worry—you'll soon learn about service workers, which will provide the support we need to swing the battle back in your favor.) But there are a few steps you can take to make sure that network requests are as quick and efficient as possible.

The following Cache-Control values can help you fine-tune where and how unversioned URLs are cached:

no-cache. This instructs the browser that it must revalidate with the server every time before using a cached version of the URL.
no-store. This instructs the browser and other intermediate caches (like CDNs) to never store any version of the file.
private. Browsers can cache the file but intermediate caches cannot.
public. The response can be stored by any cache.

Check out Appendix: Cache-Control flowchart to visualize the process of deciding which Cache-Control value(s) to use. Note also that Cache-Control can accept a comma-separated list of directives. See Appendix: Cache-Control examples.

Along with that, setting one of two additional response headers can also help: either ETag or Last-Modified. As mentioned in Response headers, ETag and Last-Modified both serve the same purpose: determining if the browser needs to re-download a cached file that has expired. ETag is the recommended approach because it's more accurate.

ETag example

Assume that 120 seconds have passed since the initial fetch and the browser has initiated a new request for the same resource. First, the browser checks the HTTP Cache and finds the previous response. Unfortunately, the browser can't use the previous response because the response has now expired. At this point, the browser could dispatch a new request and fetch the new full response. However, that's inefficient because if the resource hasn't changed, then there's no reason to download the same information that's already in the cache! That's the problem that validation tokens, as specified in the ETag header, are designed to solve. The server generates and returns an arbitrary token, which is typically a hash or some other fingerprint of the contents of the file. The browser doesn't need to know how the fingerprint is generated; it only needs to send it to the server on the next request. If the fingerprint is still the same, then the resource hasn't changed and the browser can skip the download.

By setting ETag or Last-Modified, you'll end up making the revalidation request much more efficient. They end up triggering the If-Modified-Since or If-None-Match request headers that were mentioned in Request headers.

When a properly configured web server sees those incoming request headers, it can confirm whether the version of the resource that the browser already has in its HTTP Cache matches the latest version on the web server. If there's a match, then the server can respond with a 304 Not Modified HTTP response, which is the equivalent of "Hey, keep using what you've already got!" There's very little data to transfer when sending this type of response, so it's usually much faster than having to actually send back a copy of the actual resource being requested.

The browser requests /file from the server and includes the If-None-Match header to instruct the server to only return the full file if the ETag of the file on the server doesn't match the browser's If-None-Match value. In this case, the 2 values did match, so the server returns a 304 Not Modified response with instructions on how much longer the file should be cached (Cache-Control: max-age=120).

Summary #

The HTTP Cache is an effective way to improve load performance because it reduces unnecessary network requests. It's supported in all browsers and doesn't take too much work to set up.

The following Cache-Control configurations are a good start:

Cache-Control: no-cache for resources that should be revalidated with the server before every use.
Cache-Control: no-store for resources that should never be cached.
Cache-Control: max-age=31536000 for versioned resources.

And the ETag or Last-Modified header can help you revalidate expired cache resources more efficiently.

Learn more #

If you're looking to go beyond the basics of using the Cache-Control header, check out Jake Archibald's Caching best practices & max-age gotchas guide.

See Love your cache for guidance on how to optimize your cache usage for return visitors.

Appendix: More tips #

If you have more time, here are further ways that you can optimize your usage of the HTTP Cache:

Use consistent URLs. If you serve the same content on different URLs, then that content will be fetched and stored multiple times.
Minimize churn. If part of a resource (such as a CSS file) updates frequently, whereas the rest of the file does not (such as library code), consider splitting the frequently updating code into a separate file and using a short duration caching strategy for the frequently updating code and a long caching duration strategy for the code that doesn't change often.
Check out the new stale-while-revalidate directive if some degree of staleness is acceptable in your Cache-Control policy.

Appendix: `Cache-Control` flowchart #

Appendix: `Cache-Control` examples #

`Cache-Control` value	Explanation
`max-age=86400`	The response can be cached by browsers and intermediary caches for up to 1 day (60 seconds x 60 minutes x 24 hours).
`private, max-age=600`	The response can be cached by the browser (but not intermediary caches) for up to 10 minutes (60 seconds x 10 minutes).
`public, max-age=31536000`	The response can be stored by any cache for 1 year.
`no-store`	The response is not allowed to be cached and must be fetched in full on every request.

Service workers and the Cache Storage API

2018-11-05T00:00:00Z

You're locked in a struggle for network reliability. The browser's HTTP cache is your first line of defense, but as you've learned, it's only really effective when loading versioned URLs that you've previously visited. On its own, the HTTP cache is not enough.

Fortunately, two newer tools are available to help turn the tide in your favor: service workers and the Cache Storage API. Since they're so often used together, it's worth learning about them both at the same time.

Service workers #

A service worker is built into the browser and controlled by a bit of extra JavaScript code that you are responsible for creating. You deploy this alongside the other files that make up your actual web application.

A service worker has some special powers. Among other duties, it patiently waits for your web app to make an outgoing request, and then springs into action by intercepting it. What the service worker does with this intercepted request is up to you.

For some requests, the best course of action might be just to allow the request to continue on to the network, just like what would happen if there were no service worker at all.

For other requests, though, you can take advantage of something more flexible than the browser's HTTP cache, and return a reliably fast response without having to worry about the network. That entails using the other piece of the puzzle: the Cache Storage API.

The Cache Storage API #

Browser support

Chrome 43, Supported 43
Firefox 41, Supported 41
Edge 16, Supported 16
Safari 11.1, Supported 11.1

Source

The Cache Storage API opens up a whole new range of possibilities, by giving developers complete control over the contents of the cache. Instead of relying on a combination of HTTP headers and the browser's built-in heuristics, the Cache Storage API exposes a code-driven approach to caching. The Cache Storage API is particularly useful when called from your service worker's JavaScript.

Wait… there's another cache to think about now? #

You're probably asking yourself questions like "Do I still need to configure my HTTP headers?" and "What can I do with this new cache that wasn't possible with the HTTP cache?" Don't worry—those are natural reactions.

It's still recommended that you configure the Cache-Control headers on your web server, even when you know that you're using the Cache Storage API. You can usually get away with setting Cache-Control: no-cache for unversioned URLs, and/or Cache-Control: max-age=31536000 for URLs that contain versioning information, like hashes.

When populating the Cache Storage API cache, the browser defaults to checking for existing entries in the HTTP cache, and uses those if found. If you're adding versioned URLs to the Cache Storage API cache, the browser avoids an additional network request. The flip side of this is that if you're using misconfigured Cache-Control headers, like specifying a long-lived cache lifetime for an unversioned URL, you can end up making things worse by adding that stale content to the Cache Storage API. Getting your HTTP cache behavior sorted is a prerequisite for effectively using the Cache Storage API.

As for what's now possible with this new API, the answer is: a lot. Some common uses that would be difficult or impossible with just the HTTP cache include:

Use a "refresh in the background" approach to cached content, known as stale-while-revalidate.
Impose a cap on the maximum number of assets to cache, and implement a custom expiration policy to remove items once that limit is reached.
Compare previously cached and fresh network responses to see if anything's changed, and enable the user to update content (with a button, for example) when data has actually been updated.

Check out The Cache API: A quick guide to learn more.

API nuts and bolts #

There are some things to keep in mind about the API's design:

Request objects are used as the unique keys when reading and writing to these caches. As a convenience, you can pass in a URL string like 'https://example.com/index.html' as the key instead of an actual Request object, and the API will automatically handle that for you.
Response objects are used as the values in these caches.
The Cache-Control header on a given Response is effectively ignored when caching data. There are no automatic, built-in expiration or freshness checks, and once you store an item in the cache, it will persist until your code explicitly removes it. (There are libraries to simplify cache maintenance on your behalf. They'll be covered later on in this series.)
Unlike with older, synchronous APIs such as LocalStorage, all Cache Storage API operations are asynchronous.

A quick detour: promises and async/await #

Service workers and the Cache Storage API use asynchronous programming concepts. In particular, they rely heavily on promises to represent the future result of async operations. You should familiarize yourself with promises, and the related async/await syntax, before diving in.

Don't deploy that code… yet #

While they provide an important foundation, and can be used as-is, both service workers and the Cache Storage API are effectively lower-level building blocks, with a number of edge cases and "gotchas". There are some higher-level tools that can help smooth the difficult bits of those APIs, and provide all you need to build a production-ready service worker. The next guide covers one such tool: Workbox.

Explore DevTools Network panel

2018-11-05T00:00:00Z

This codelab walks you through the process of interpreting all of the network traffic for a somewhat complex sample application. At the end of the exercise, you'll have the skills you need to figure out what your own web application is loading and when it's making each request.

Navigate to the Network Panel #

Navigate to the Network panel to see the network traffic for the demo application.

To preview the site, press View App. Then press Fullscreen .
Press `Control+Shift+J` (or `Command+Option+J` on Mac) to open DevTools.
Click the Network tab.
Reload the page to see the network traffic.

The Network panel shows all the assets loaded because of your initial navigation:

How to interpret the entries #

Each row of recorded network traffic represents a single request and response pair.

The first row, with type document, is the initial navigation request for the web app's HTML. This is the source for the waterfall; each of the subsequent requests for additional assets (known as subresources of the main document) flow from this original source.

The second and third rows, showing a CSS stylesheet and a script subresource being loaded, are dependent requests that were initiated by the main document.

Looking at when those requests are made, the waterfall diagram shows that they're not started until very late in the process of responding to the navigation request.

Taken together, the requests for the HTML document, CSS, and JavaScript are needed to display the full page during the initial navigation.

Create some additional runtime requests #

With the Network panel still open and recording, it's time to simulate something common for a lot of web apps: additional API requests used to add more data to the page after the initial navigation is complete.

Trigger these additional requests by clicking Find Me in the app and then Allow in the popup that appears. This will allow the site to access your current location:

Once the web app has a location to work with, clicking Find Nearby Wikipedia Entries results in several additional network requests. You should see something like this:

Interpret the new entries #

As before, each row of recorded network traffic represents a single request and response pair.

The first row of the new entries represents a request with a type of fetch, which corresponds to the way the web app requests data from the Wikipedia API.

The following rows all are images (png or jpeg) associated with the Wikipedia entries. Although it's a little hard to see from the screenshot, their entries in the Waterfall column directly flow from the API response.

For all of these additional requests, the when is going to vary based on how long you've had the page open before you click on Find Nearby Wikipedia Entries. Most important here is that the when is disconnected from the initial navigation request. You can tell this from the large gap that exists in the Waterfall display, representing a period of time that passed in between the initial loading and when the Wikipedia API request is made.

Requests made after a gap of time following a navigation fall into the category of "runtime requests," as opposed to the initial set of requests used to display the page when you first navigated to it.

Summing things up #

Having gone through the steps in this codelab, you're now familiar with the tools you can use to analyze what any web application loads.

The Network panel helps you answer the question of what's being loaded, via the URLs in the Name column and the data in the Type column, along with when it's being loaded, via the waterfall display.

You've also seen that requests made by a web page can (usually) be grouped into one of two categories:

Initial requests, made right after navigating to a new page, for the HTML, JavaScript, CSS (and potentially other assets).
Runtime requests made as a result of user interaction with the page. This can often start with a request to an API, and then flow into several follow-up requests based on the API data retrieved.

Configuring HTTP caching behavior

2018-11-05T00:00:00Z

This codelab shows you how to change the HTTP caching headers returned by a Node.js-based web server, running the Express serving framework. It will also show how to confirm that the caching behavior you expect is actually being applied, using the Network panel in Chrome's DevTools.

Get familiar with the sample project #

These are the key files you will be working with in the sample project:

server.js contains the Node.js code that serves the web app's content. It uses Express to handle HTTP requests and responses. In particular, express.static() is used to serve all of the local files in the public directory, so the serve-static documentation will come in handy.
public/index.html is the web app's HTML. Like most HTML files, it does not contain any versioning information as part of its URL.
public/app.15261a07.js and public/style.391484cf.css are the web app's JavaScript and CSS assets. These files each contain a hash in their URLs, corresponding to their contents. The index.html is responsible for keeping track of which specific versioned URL to load.

Configure caching headers for our HTML #

When responding to requests for URLs that don't contain versioning info, make sure you add Cache-Control: no-cache to your response messages. Along with that, setting one of two additional response headers is recommended: either Last-Modified or ETag. The index.html falls into this category. You can break this down into two steps.

First, the Last-Modified and ETag headers are controlled by the etag and lastModified configuration options. Both of these options actually default to true for all HTTP responses, so in this current setup, you don't have to opt-in to get that behavior. But you can be explicit in your configuration anyway.

Second, you need to be able to add in the Cache-Control: no-cache header, but only for your HTML documents (index.html, in this case). The easiest way to conditionally set this header is to write a custom setHeaders function, and within that, check to see if the incoming request is for an HTML document.

Click Remix to Edit to make the project editable.

The static serving configuration in server.js starts out as this:

app.use(express.static('public'));

Make the changes described above, and you should end up with something that looks like:

app.use(express.static('public', {
  etag: true, // Just being explicit about the default.
  lastModified: true,  // Just being explicit about the default.
  setHeaders: (res, path) => {
    if (path.endsWith('.html')) {
      // All of the project's HTML files end in .html
      res.setHeader('Cache-Control', 'no-cache');
    }
  },
}));

Configure caching headers for the versioned URLs #

When responding to requests for URLs that contain "fingerprint" or versioning information, and whose contents are never meant to change, add Cache-Control: max-age=31536000 to your responses. The app.15261a07.js and style.391484cf.css fall into this category.

Building off the setHeaders function used in the last step, you can add in additional logic to check whether a given request is for a versioned URL, and if so, add the Cache-Control: max-age=31536000 header.

The most robust way of doing this is to use a regular expression to see whether the asset being requested matches a specific pattern that you know the hashes fall into. In the case of this sample project, it's always eight characters from the set of digits 0–9 and the lowercase letters a–f (i.e. hexadecimal characters). The hash is always separated by a . character on either side.

A regular expression that matches those general rules can be expressed as new RegExp('\\.[0-9a-f]{8}\\.').

Modify the setHeaders function so it looks like this:

app.use(express.static('public', {
  etag: true, // Just being explicit about the default.
  lastModified: true,  // Just being explicit about the default.
  setHeaders: (res, path) => {
    const hashRegExp = new RegExp('\\.[0-9a-f]{8}\\.');

    if (path.endsWith('.html')) {
      // All of the project's HTML files end in .html
      res.setHeader('Cache-Control', 'no-cache');
    } else if (hashRegExp.test(path)) {
      // If the RegExp matched, then we have a versioned URL.
      res.setHeader('Cache-Control', 'max-age=31536000');
    }
  },
}));

Confirm the new behavior using DevTools #

With the modifications to the static file server in place, you can check to make sure that the right headers are being set by previewing the live app with the DevTools Network panel open.

To preview the site, press View App. Then press Fullscreen .
Customize the columns that are displayed in the Network panel to include the information that is most relevant, by right-clicking in the column header:

Here, the columns to pay attention to are Name, Status, Cache-Control, ETag, and Last-Modified.

With the DevTools open to the Network panel, refresh the page.

After the page has loaded, you should see entries in the Network panel that look like the following:

The first row is for the HTML document that you navigated to. This is properly served with Cache-Control: no-cache. The HTTP response status for that request is a 304. This means that the browser knew not to use the cached HTML immediately, but instead made an HTTP request to the web server, using the Last-Modified and ETag information to see if there was any update to the HTML that it already had in its cache. The HTTP 304 response indicates that there is not updated HTML.

The next two rows are for the versioned JavaScript and CSS assets. You should see them served with Cache-Control: max-age=31536000, and the HTTP status for each is 200. Because of the configuration used, there is no actual request being made to the Node.js server, and clicking on the entry will show you additional detail, including that the response came "(from disk cache)".

The actual values for the ETag and Last-Modified columns don't matter much. The important thing is to confirm that they're being set.

Summing things up #

Having gone through the steps in this codelab, you're now familiar with how to configure the HTTP response headers in a Node.js-based web server using Express, for optimal use of the HTTP cache. You also have the steps you need to confirm that the expected caching behavior is being used, via the Network panel in Chrome's DevTools.

Working with service workers

2018-11-05T00:00:00Z

This codelab shows you how to register a service worker from within your web application, and use the Chrome DevTools to observe its behavior. It also covers some debugging techniques that you might find useful when dealing with service workers.

Get familiar with the sample project #

The files in the sample project most relevant to this codelab are:

register-sw.js starts out empty, but it will contain the code used to register the service worker. It's already being loaded via a <script> tag inside of the project's index.html.
service-worker.js is similarly empty. It's the file that will contain the service worker for this project.

Add in the service worker registration code #

A service worker (even an empty one, like the current service-worker.js file) won't be used unless it's registered first. You can do this via a call to:

navigator.serviceWorker.register(
  '/service-worker.js'
)

inside your register-sw.js file.

Before you add that code, though, there are a couple of points to take into account.

First, not every browser supports service workers. This is particularly true for older versions of browsers that don't automatically update. So it's a best practice to call navigator.serviceWorker.register() conditionally, after checking whether navigator.serviceWorker is supported.

Second, when you register a service worker, the browser runs the code in your service-worker.js file, and may potentially start downloading URLs to populate caches, depending on the code in your service worker's install and activate event handlers.

Running additional code and downloading assets can use up valuable resources that your browser could otherwise use to display the current web page. To help avoid this interference, it's a good practice to delay registering a service worker until the browser has finished rendering the current page. A convenient way of approximating this is to wait until the window.load event has been fired.

Putting those two points together, add this general-purpose service worker registration code to your register-sw.js file:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js');
  });
}

Add some service worker logging code #

Your service-worker.js file is where all the logic for your service worker implementation would normally go. You'd use a mix of the service worker lifecycle events, the Cache Storage API, and knowledge about your web app's network traffic to create a perfectly crafted service worker, ready to handle all of your web app's requests.

But… that's all for learning later. At this stage, the focus is on observing various service worker events, and getting comfortable using Chrome's DevTools to debug the state of your service worker.

To that end, add in the following code to service-worker.js, which will log messages to the DevTools console in response to various events (but not do much else):

self.addEventListener('install', (event) => {
  console.log('Inside the install handler:', event);
});

self.addEventListener('activate', (event) => {
  console.log('Inside the activate handler:', event);
});

self.addEventListener(fetch, (event) => {
  console.log('Inside the fetch handler:', event);
});

Get familiar with the Service Workers panel in DevTools #

Now that you've got the code added to register-sw.js and service-worker.js files, it's time to visit the Live version of your sample project, and observe the service worker in action.

To preview the site, press View App. Then press Fullscreen .
Press `Control+Shift+J` (or `Command+Option+J` on Mac) to open DevTools.
Click the Console tab.

You should see something like the following log messages, showing that the service worker has been installed and activated:

Then visit the Applications tab, and select the Service Workers panel. You should see something like the following:

This lets you know that there's a service worker with a source URL of service-worker.js, for the web app solar-donkey.glitch.me, that's currently activated and running. It also tells you that there's currently one client (open tab) that's being controlled by the service worker.

You can use the links on this panel, like Unregister, or stop, to make changes to the currently registered service worker for debugging purposes.

Trigger the service worker update flow #

One of the key concepts to understand when developing with service workers is the idea of an update flow.

After your users visit a web app which registers a service worker, they'll end up with the code for the current copy of service-worker.js installed on their local browser. But what happens when you make updates to the version of service-worker.js that's stored on your web server?

When a repeat visitor returns to a URL that's within the scope of a service worker, the browser will automatically request the latest service-worker.js and check for any changes. If anything in the service worker script is different, then the new service worker will get a chance to install, activate, and eventually take control.

You can simulate this update flow by going back to the code editor for your project, and making any change to the code. One quick change would be to replace

self.addEventListener('install', (event) => {
  console.log('Inside the install handler:', event);
});

with

self.addEventListener('install', (event) => {
  console.log('Inside the UPDATED install handler:', event);
});

After making that change, return to the Live version of your sample app, and reload the page with the DevTools Application tab still open. You should see something like the following:

This shows that there are two versions of your service worker installed at this point. The previous version, which was already activated, is running and in control of the current page. The updated version of the service worker is listed right below. It's in the waiting state, and will remain waiting until all of the open tabs that are controlled by the old service worker are closed.

This default behavior ensures that if your new service worker has a fundamental difference in behavior from your old one—like a fetch handler which responds with resources that are incompatible with older versions of your web app—it won't go into effect until a user has shut down all previous instances of your web app.

Summing things up #

You should now be comfortable with the process of registering a service worker and observing a service worker's behavior using Chrome's DevTools.

You're now in a good position to start implementing caching strategies, and all the good stuff that will help your web app load both reliably and reliably fast.

Identify resources loaded from the network

2018-11-05T00:00:00Z

The Network panel in your browser's DevTools helps identify what resources are loaded and when they are loaded. Each row in the Network panel corresponds to a specific URL that your web app has loaded.

Know what you load #

Coming up with the right caching strategies for your web application requires getting a handle on what exactly you're loading. When building a reliable web application, the network can be subject to all kinds of dark forces. You need to understand the network's vulnerabilities if you hope to cope with them in your app.

You might think that you already have a pretty good idea as to what your web application loads. If you're just using a small scattering of static HTML, JavaScript, CSS, and image files, that might be true. But as soon as you start mixing in third-party resources hosted on content delivery networks, using dynamic API requests and server-generated responses, the picture quickly becomes murkier.

A caching strategy that makes sense for a few small CSS files probably won't make sense for hundreds of large images, for instance.

Know when you load #

Another part of the overall loading picture is when everything gets loaded.

Some requests to the network, such as the navigation request for your initial HTML, are made unconditionally as soon as a user visits a given URL. That HTML might contain hardcoded references to critical CSS or JavaScript files that must also load in order to display your interactive page. These requests all sit in your critical loading path. You will need to aggressively cache these to be reliably fast.

Other resources, such as API requests or lazy-loaded assets, might not start to load until well after all of the initial loading is complete. If those requests only happen following a specific sequence of user interactions, then a completely different set of resources might end up being requested across multiple visits to the same page. A less aggressive caching strategy is often appropriate for content that you've identified as being outside the critical loading path.

The Name and Type columns help with the what #

The Name and Type columns help provide a meaningful picture of what's being loaded. The answer to "what's loading?" in the example above is a total of four URLs, each representing a unique type of content.

The Name represents the URL that your browser requested—though you'll only see the last portion of the URL's path listed. For example, if https://example.com/main.css is loaded, you'd only end up seeing main.css listed under Name.

The last few characters of the URL's path, following the period (e.g. "css"), are known as the URL's extension. The URL's extension generally tells you what type of resource is being requested, and maps directly to the information shown in the Type column. For example, v2.html is a document, and main.css is a stylesheet.

The Waterfall column helps with the when #

Examine the Waterfall column, starting at the top and working your way down. The length of each bar represents the total amount of time that was spent loading each resource. How can you tell the difference between a request that's made as part of the critical loading path and a request that's fired off dynamically, long after the page's initial load is complete?

The first request in the waterfall is always going to be for the HTML document, for example, v2.html. All of the subsequent requests will flow (like a waterfall!) from this initial navigation request, based on what images, scripts, and styles the HTML document references.

The waterfall shows that as soon as v2.html has finished loading, the requests for the assets it references (also referred to as subresources) start. The browser can request multiple subresources at the same time, and that's represented by the overlapping bars in the Waterfall column for main.css and logo.svg. Finally, you can see from the screenshot that main.js starts loading last, and it finishes loading after the other three URLs have completed as well.

Precaching with Workbox

2018-11-05T00:00:00Z

One feature of service workers is the ability to save files to the cache when the service worker is installing. This is referred to as "precaching". Precaching makes it possible to serve cached files to the browser without going to the network. Use precaching for critical assets that your site needs even when offline: main page, styles, fallback image and essential scripts.

Why should you use Workbox? #

Using Workbox for precaching is optional. You can write your own code to precache critical assets when the service worker is installing. The primary benefit of using Workbox is its out-of-the-box version control. You'll run into a lot less trouble updating precached assets using Workbox than if you had to manage the versioning and updating of these files on your own.

Precache manifests #

Precaching is driven by a list of URLs and associated versioning information for each URL. Taken together, this information is known as a precache manifest. The manifest is the "source of truth" for the state of everything meant to be in the precache for a given version of a web app. A precache manifest, in the format used by Workbox, looks something like:

[{
  url: 'app.abcd1234.js'
}, {
  url: 'offline.svg',
  revision: '7836745f'
}, {
  url: 'index.html',
  revision: '518747aa'
}]

When the service worker is installed, three cache entries are created in the Cache Storage, for each of the three listed URLs. The first asset has versioning information already included in its URL (app is the actual file name, and .abcd1234 contains the versioning information, right before the file extension .js). Workbox's build tools can detect this and exclude a revision field. The other two assets do not include any versioning info in their URLs, so Workbox's build tools create a separate revision field, containing a hash of the local file's contents.

Serving precached resources #

Adding assets to the cache is just one part of the precaching story—once the assets are cached, they need to respond to outgoing requests. That requires a fetch event listener in your service worker that can check which URLs have been precached, and return those cached responses reliably, bypassing the network in the process. Since the service worker checks the cache for responses (and uses those before the network), this is called a cache-first strategy.

Efficient updates #

A precache manifest provides an exact representation of the expected cache state; if a URL/revision combination in the manifest changes, a service worker knows that the previous cached entry is no longer valid, and needs to be updated. It only takes a single network request, made automatically by the browser as part of the service worker update check, to determine which precached URLs need to be refreshed.

Updates to precached resources #

As you release new versions of your web app over time, you need to keep previously precached URLs up to date, precache new assets, and delete outdated entries. As long as you continue generating a full precache manifest each time you rebuild your site, that manifest serves as the "source of truth" for your precache state at any point in time.

If there's an existing URL with a new revision field, or if any URLs have been added or dropped from the manifest, that's a sign to your service worker that updates need to be performed, as part of the install and activate event handlers. For instance, if you've made some changes to your site and rebuilt, your latest precache manifest might have undergone the following changes:

[{
  url: 'app.ffaa4455.js'
}, {
  url: 'offline.svg',
  revision: '7836745f'
}, {
  url: 'index.html',
  revision: '518747aa'
}]

Each of these changes tells your service worker that new requests need to be made to update previously cached entries ('offline.svg' and 'index.html') and cache new URLs ('app.ffaa4455.js'), as well as deletions to clean up URLs that are no longer used ('app.abcd1234.js').

True "app store" install experience #

Another benefit of precaching is that you can give your users an experience that would otherwise be difficult to achieve outside of an "app store" installation. Once a user visits any page on your web app for the first time, you can potentially precache all of the URLs needed to display any of your web app's views ahead of time, without having to wait until they visit each individual view.

When a user installs an app, they expect every part to display quickly, not just the views that they've gone to in the past. Precaching brings that same experience to web apps.

Which of your assets should be precached? #

Refer back to the Identify what's being loaded guide to get a good picture of which URLs make the most sense to precache. The general rule is to precache any HTML, JavaScript, or CSS that's loaded early on and is crucial to displaying the basic structure of a given page.

It's preferable to avoid precaching media or other assets that are loaded later (unless crucial for your web app's functionality). Instead, use a runtime caching strategy to ensure these assets are cached-as-you-go.

Always keep in mind that precaching involves using network bandwidth and storage on a user's device (just like installing an app from an app store does). It's up to you as the developer to precache judiciously, and avoid a bloated precache manifest.

Workbox's build tools help by telling you the number of items in the precache manifest as well as the total size of the precache payload.

Repeat visitors to your web app benefit in the long run from the upfront cost of precaching, since the ability it offers to avoid the network quickly pays for itself in saved bandwidth over time.

Runtime caching with Workbox

2018-11-05T00:00:00Z

Runtime caching refers to gradually adding responses to a cache "as you go". While runtime caching doesn't help with the reliability of the current request, it can help make future requests for the same URL more reliable.

The browser's HTTP cache is an example of runtime caching; it's only populated after a request for a given URL. But service workers allow you to implement runtime caching that goes beyond what the HTTP cache alone can offer.

Getting strategic #

As opposed to precaching (which always tries to serve a set of predefined files from a cache), runtime caching can combine network and cache access in multiple ways. Each combination is generally referred to as a caching strategy. Key caching strategies include:

Network-first
Cache-first
Stale-while-revalidate

Network-first #

In this approach, your service worker first attempts to retrieve a response from the network. If the network request succeeds, great! The response is returned to your web app, and a copy of the response is stored using the Cache Storage API—either creating a new entry, or updating a previous entry for the same URL.

If the network request fails entirely, or takes too long to return a response, then the most recent response from the cache is returned instead.

Cache-first #

A cache-first strategy is effectively the opposite of network-first. In this approach, when your service worker intercepts a request, it first uses the Cache Storage API to see whether there's a cached response available. If there is, that response is returned to the web app.

If there's a cache miss, though, then the service worker will go to the network and attempt to retrieve a response there. Assuming that network request is successful, it's returned to your web app and a copy is saved in a cache. This cached copy will be used to bypass the network the next time a request for the same URLs is made.

Stale-while-revalidate #

Stale-while-revalidate is something of a hybrid. When using it, your service worker will immediately check for a cached response and, if one is found, pass it back to your web app.

In the meantime, regardless of whether there was a cache match, your service worker also fires off a network request to get back a "fresh" response. This response is used to update any previously cached response. If the initial cache check was a miss, a copy of the network response is also passed back to your web app.

Why should you use Workbox? #

These caching strategies amount to recipes that you would normally have to rewrite in your own service worker, again and again. Instead of resorting to that, Workbox offers them packaged up as part of its strategies library, ready for you to drop in to your service worker.

Workbox also provides versioning support, allowing you to automatically expire cached entries, or notify your web app when updates to a previously cached entry occur.

Which of your assets should be cached, with which strategies? #

Runtime caching can be viewed as a complement to precaching. If all of your assets are already being precached, then you're done—there's nothing that needs to be cached at runtime. Chances are, for any relatively complex web app, you're not going to be precaching everything though.

Larger media files, assets that are served from a third-party host like a CDN, or API responses, are just a few examples of the types of assets that can't be effectively precached. Use the Network panel in DevTools to identify requests that fall into this category, and for each of them, think about what tradeoff of freshness vs. reliability is appropriate.

Use stale-while-revalidate to prioritize reliability over freshness #

Since a stale-while-revalidate strategy returns a cached response almost immediately—after the cache has been populated via the first request—you'll end up seeing reliably fast performance when using this strategy. This comes with the tradeoff of getting back response data that could be stale in comparison to what would have been retrieved from the network. Using this strategy works best for assets like user profile images or the initial API responses used to populate a view, when you know that showing something immediately is key, even if it's an older value.

Use network-first to prioritize freshness over reliability #

In some sense, using a network-first strategy is admitting defeat in your battle against the network—it's given priority, but that brings with it uncertainty about reliability. For certain types of assets, seeing a fresh response is preferable to getting back stale information. You might prefer freshness when making an API request for the text of an article that is updated frequently, for instance.

By using a network-first strategy inside of a service worker, instead of just going against the network directly, you have the benefit of being able to fall back to something, even if it's a potentially stale response. You won't be reliably fast, but at least you'll be reliable while offline.

Use cache-first for versioned URLs #

In a cache-first strategy, once an entry is cached, it's never updated. For that reason, make sure that you only use it with assets that you know are unlikely to change. In particular, it works best for URLs that contain versioning information—the same sort of URLs that should also be served with a Cache-Control: max-age=31536000 response header.

Workbox: your high-level service worker toolkit

2018-11-05T00:00:00Z

Two APIs play a crucial role in building reliable web apps: Service Worker and Cache Storage. But using them effectively—without introducing subtle bugs or bumping into edge cases—can be a challenge. For example, errors in your service worker code can cause caching problems; users might be shown out-of-date content or broken links.

Workbox is a high-level service worker toolkit built on top of the Service Worker and Cache Storage APIs. It provides a production-ready set of libraries for adding offline support to web apps. The toolkit is structured into two collections: tools that help manage code that runs inside of your service worker, and tools that integrate with your build process.

Runtime code #

This is the code that runs inside of your service worker script and controls how it intercepts outgoing requests and interacts with the Cache Storage API. Workbox has a dozen or so library modules in total, that each handle a variety of specialized use cases. The most important modules determine whether the service worker will respond (known as routing), and how it will respond (known as the caching strategy).

Build integration #

Workbox offers command line, Node.js module, and webpack plugin tools that provide alternative ways to accomplish two things:

Create a service worker script based on a set of configuration options. The generated service worker uses Workbox's runtime libraries "under the hood" to put into action the caching strategies you configure.
Generate a list of URLs that should be "precached", based on configurable patterns to include and exclude files generated during your build process.

Why should you use Workbox? #

Using Workbox when building your service worker is optional—there are a number of guides out there that walk through common caching strategies from a "vanilla" service worker perspective. If you do decide to use Workbox, here are some of its benefits.

Cache management #

Workbox handles cache updates for you, either tied in to your build process when using precaching, or via configurable size/age policies when using runtime caching. The underlying Cache Storage API is powerful, but it does not have any built-in support for cache expiration. Tools like Workbox fill that gap.

Extensive logging and error reporting #

When you're getting started with service workers, figuring out why something is being cached (or, equally frustrating, why it isn't cached) is a challenge. Workbox automatically detects when you're running a development version of your website on localhost, and turns on debug logging in your browser's JavaScript console.

By following along with the log messages, you can get to the root of any configuration or invalidation problems much more quickly than if you were going it alone.

A tested, cross-browser codebase #

Workbox is developed against a cross-browser test suite, and when possible, automatically falls back to alternative implementations of features that are missing from certain browsers.

The workbox-broadcast-cache-update module uses the Broadcast Channel API when available, and falls back to a postMessage()-based implementation on browsers that lack support.
The workbox-background-sync module uses the Background Sync API if possible, and if not, falls back to retrying queued events each time the service worker starts up.

How should you use Workbox? #

Framework integration #

If you're starting a new project from scratch, you can take advantage of the Workbox integration found in many popular starter kits and add-on plugins:

Add Workbox to your existing build process #

If you already have a build process for your site in place, dropping in the appropriate command line, Node.js module, or webpack plugin tool may be all you need to start using Workbox.

In particular, the Workbox command line interface makes it easy to get up and running, featuring a wizard mode that will check your local development environment and suggest a reasonable default configuration that you could use moving forward:

workbox wizard
? What is the root of your web app (i.e. which directory do you deploy)? src/
? Which file types would you like to precache? css, js, html
? Where would you like your service worker file to be saved? build/sw.js
? Where would you like to save these configuration options? workbox-config.js

To build your service worker, run workbox generateSW workbox-config.js as part of a build process. See the generateSW documentation for details. You can further customize your service worker by making changes to workbox-config.js. See the documentation of the options for details.

Use Workbox at runtime in an existing service worker #

If you have an existing service worker and want to try out Workbox's runtime libraries, import Workbox from its official CDN and start using it for runtime caching right away. This use case means that you won't be able to take advantage of precaching (which requires build-time integration), but it's great for prototyping and trying out different caching strategies on the fly.

// Replace 3.6.3 with the current version number of Workbox.
importScripts('https://storage.googleapis.com/workbox-cdn/releases/3.6.3/workbox-sw.js');

workbox.routing.registerRoute(
  new RegExp('\.png$'),
  workbox.strategies.cacheFirst({
    cacheName: 'images-cache',
  })
);

Service worker registration

2016-11-28T00:00:00Z

Service workers can meaningfully speed up repeat visits to your web app, but you should take steps to ensure that a service worker's initial installation doesn't degrade a user's first-visit experience.

Generally, deferring service worker registration until after the initial page has loaded will provide the best experience for users, especially those on mobile devices with slower network connections.

Common registration boilerplate #

If you've ever read about service workers, you've probably come across boilerplate substantially similar to the following:

if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/service-worker.js');
}

This might sometimes be accompanied by a few console.log() statements, or code that detects an update to a previous service worker registration, as a way of letting users know to refresh the page. But those are just minor variations on the standard few lines of code.

So, is there any nuance to navigator.serviceWorker.register? Are there any best practices to follow? Not surprisingly (given that this article doesn't end right here), the answer to both is "yes!"

A user's first visit #

Let's consider a user's first visit to a web app. There's no service worker yet, and the browser has no way of knowing in advance whether there will be a service worker that is eventually installed.

As a developer, your priority should be to make sure that the browser quickly gets the minimal set of critical resources needed to display an interactive page. Anything that slows down retrieving those responses is the enemy of a speedy time-to-interactive experience.

Now imagine that in the process of downloading the JavaScript or images that your page needs to render, your browser decides to start a background thread or process (for the sake of brevity, we'll assume it's a thread). Assume that you're not on a beefy desktop machine, but rather the type of underpowered mobile phone that much of the world considers their primary device. Spinning up this extra thread adds contention for CPU time and memory that your browser might otherwise spend on rendering an interactive web page.

An idle background thread is unlikely to make a significant difference. But what if that thread isn't idle, but instead decides that it's also going to start downloading resources from the network? Any concern about CPU or memory contention should take a backseat to worries about the limited bandwidth available to many mobile devices. Bandwidth is precious, so don't undermine critical resources by downloading secondary resources at the same time.

All of this is to say that spinning up a new service worker thread to download and cache resources in the background can work against your goal of providing the shortest time-to-interactive experience the first time a user visits your site.

Improving the boilerplate #

The solution is to control start of the service worker by choosing when to call navigator.serviceWorker.register(). A simple rule of thumb would be to delay registration until after the load event fires on window, like so:

if ('serviceWorker' in navigator) {
    window.addEventListener('load', function() {
    navigator.serviceWorker.register('/service-worker.js');
    });
}

But the right time to kick off the service worker registration can also depend on what your web app is doing right after it loads. For example, the Google I/O 2016 web app features a short animation before transitioning to the main screen. Our team found that kicking off the service worker registration during the animation could lead to jankiness on low-end mobile devices. Rather than giving users a poor experience, we delayed service worker registration until after the animation, when the browser was most likely to have a few idle seconds.

Similarly, if your web app uses a framework that performs additional setup after the page has loaded, look for a framework-specific event that signals when that work is done.

Subsequent visits #

We've been focusing on the first visit experience up until now, but what impact does delayed service worker registration have on repeat visits to your site? While it might surprise some folks, there shouldn't be any impact at all.

When a service worker is registered, it goes through the install and activate lifecycle events. Once a service worker is activated, it can handle fetch events for any subsequent visits to your web app. The service worker starts before the request for any pages under its scope is made, which makes sense when you think about it. If the existing service worker weren't already running prior to visiting a page, it wouldn't have a chance to fulfill fetch events for navigation requests.

So once there's an active service worker, it doesn't matter when you call navigator.serviceWorker.register(), or in fact, whether you call it at all. Unless you change the URL of the service worker script, navigator.serviceWorker.register() is effectively a no-op during subsequent visits. When it's called is irrelevant.

Reasons to register early #

Are there any scenarios in which registering your service worker as early as possible makes sense? One that comes to mind is when your service worker uses clients.claim() to take control of the page during the first visit, and the service worker aggressively performs runtime caching inside of its fetch handler. In that situation, there's an advantage to getting the service worker active as quickly as possible, to try to populate its runtime caches with resources that might come in handy later. If your web app falls into this category, it's worth taking a step back to make sure that your service worker's install handler doesn't request resources that fight for bandwidth with the main page's requests.

Testing things out #

A great way to simulate a first visit is to open your web app in a Chrome Incognito window, and look at the network traffic in Chrome's DevTools. As a web developer, you probably reload a local instance of your web app dozens and dozens of times a day. But by revisiting your site when there's already a service worker and fully populated caches, you don't get the same experience that a new user would get, and it's easy to ignore a potential problem.

Here's an example illustrating the difference that registration timing could make. Both screenshots are taken while visiting a sample app in Incognito mode using network throttling to simulate a slow connection.

The screenshot above reflects the network traffic when the sample was modified to perform service worker registration as soon as possible. You can see precaching requests (the entries with the gear icon next to them, originating from the service worker's install handler) interspersed with requests for the other resources needed to display the page.

In the screenshot above, service worker registration was delayed until after the page had loaded. You can see that the precaching requests don't start until all the resources have been fetched from the network, eliminating any contention for bandwidth. Moreover, because some of the items we're precaching are already in the browser's HTTP cache—the items with (from disk cache) in the Size column—we can populate the service worker's cache without having to go to the network again.

Bonus points if you run this sort of test from an actual, low-end device on a real mobile network. You can take advantage of Chrome's remote debugging capabilities to attach an Android phone to your desktop machine via USB, and ensure that the tests you're running actually reflect the real-world experience of many of your users.

Conclusion #

To summarize, making sure that your users have the best first-visit experience should be a top priority. Delaying service worker registration until after the page has loaded during the initial visit can help ensure that. You'll still get all the benefits of having a service worker for your repeat visits.

A straightforward way to ensure to delay your service worker's initial registration until after the first page has loaded is to use the following:

if ('serviceWorker' in navigator) {
    window.addEventListener('load', function() {
    navigator.serviceWorker.register('/service-worker.js');
    });
}

Service Workers in Production

2015-10-01T00:00:00Z

Summary #

Learn how we used service worker libraries to make the Google I/O 2015 web app fast, and offline-first.

Overview #

This year’s Google I/O 2015 web app was written by Google’s Developer Relations team, based on designs by our friends at Instrument, who wrote the nifty audio/visual experiment. Our team’s mission was to ensure that the I/O web app (which I’ll refer to by its codename, IOWA) showcased everything the modern web could do. A full offline-first experience was at the top of our list of must-have features.

If you’ve read any of the other articles on this site recently, you’ve undoubtedly encountered service workers, and you won’t be surprised to hear that IOWA’s offline support is heavily reliant on them. Motivated by the real-world needs of IOWA, we developed two libraries to handle two different offline use cases: sw-precache to automate precaching of static resources, and sw-toolbox to handle runtime caching and fallback strategies.

The libraries complement each other nicely, and allowed us to implement a performant strategy in which IOWA’s static content “shell” was always served directly from the cache, and dynamic or remote resources were served from the network, with fallbacks to cached or static responses when needed.

Precaching with `sw-precache` #

IOWA’s static resources—its HTML, JavaScript, CSS, and images—provide the core shell for the web application. There were two specific requirements that were important when thinking about caching these resources: we wanted to make sure that most static resources were cached, and that they were kept up to date. sw-precache was built with those requirements in mind.

Build-time Integration #

sw-precache with IOWA’s gulp-based build process, and we rely on a series of glob patterns to ensure that we generate a complete list of all the static resources IOWA uses.

staticFileGlobs: [
    rootDir + '/bower_components/**/*.{html,js,css}',
    rootDir + '/elements/**',
    rootDir + '/fonts/**',
    rootDir + '/images/**',
    rootDir + '/scripts/**',
    rootDir + '/styles/**/*.css',
    rootDir + '/data-worker-scripts.js'
]

Alternative approaches, like hard coding a list of file names into an array, and remembering to bump a cache version number each time any of those files changes were far too error prone, especially given that we had multiple team members checking in code. No one wants to break offline support by leaving out a new file in a manually maintained array! Build-time integration meant we could make changes to existing files and add new files without having those worries.

Updating Cached Resources #

sw-precache generates a base service worker script that includes a unique MD5 hash for each resource that gets precached. Each time an existing resource changes, or a new resource is added, the service worker script is regenerated. This automatically triggers the service worker update flow, in which the new resources are cached and out of date resources are purged. Any existing resources that have identical MD5 hashes are left as-is. That means users who have visited the site before only end up downloading the minimal set of changed resources, leading to a much more efficient experience than if the entire cache was expired en masse.

Each file that matches one of the glob patterns is downloaded and cached the first time a user visits IOWA. We made an effort to ensure that only critical resources needed to render the page were precached. Secondary content, like the media used in the audio/visual experiment, or the profile images of the sessions’ speakers, were deliberately not precached, and we instead used the sw-toolbox library to handle offline requests for those resources.

`sw-toolbox`, for All Our Dynamic Needs #

As mentioned, precaching every resource that a site needs to work offline isn’t feasible. Some resources are too large or infrequently used to make it worthwhile, and other resources are dynamic, like the responses from a remote API or service. But just because a request isn’t precached doesn’t mean it has to result in a NetworkError. sw-toolbox gave us the flexibility to implement request handlers that handle runtime caching for some resources and custom fallbacks for others. We also used it to update our previously cached resources in response to push notifications.

Here are a few examples of custom request handlers that we built on top of sw-toolbox. It was easy to integrate them with the base service worker script via sw-precache’s importScripts parameter, which pulls standalone JavaScript files into the scope of the service worker.

Audio/Visual Experiment #

For the audio/visual experiment, we used sw-toolbox’s networkFirst cache strategy. All HTTP requests matching the URL pattern for the experiment would first be made against the network, and if a successful response was returned, that response would then be stashed away using the Cache Storage API. If a subsequent request was made when the network was unavailable, the previously cached response would be used.

Because the cache was automatically updated each time a successful network response came back, we didn’t have to specifically version resources or expire entries.

toolbox.router.get('/experiment/(.+)', toolbox.networkFirst);

Speaker Profile Images #

For speaker profile images, our goal was to display a previously cached version of a given speaker’s image if it was available, falling back to the network to retrieve the image if it wasn’t. If that network request failed, as a final fallback, we used a generic placeholder image that was precached (and therefore would always be available). This is a common strategy to use when dealing with images that could be replaced with a generic placeholder, and it was easy to implement by chaining sw-toolbox’s cacheFirst and cacheOnly handlers.

var DEFAULT_PROFILE_IMAGE = 'images/touch/homescreen96.png';

function profileImageRequest(request) {
    return toolbox.cacheFirst(request).catch(function() {
    return toolbox.cacheOnly(new Request(DEFAULT_PROFILE_IMAGE));
    });
}

toolbox.precache([DEFAULT_PROFILE_IMAGE]);
toolbox.router.get('/(.+)/images/speakers/(.*)',
                    profileImageRequest,
                    {origin: /.*\.googleapis\.com/});

Profile images from a session page.

Updates to Users’ Schedules #

One of the key features of IOWA was allowing signed-in users to create and maintain a schedule of sessions they planned on attending. Like you’d expect, session updates were made via HTTP POST requests to a backend server, and we spent some time working out the best way to handle those state-modifying requests when the user is offline. We came up with a combination of a that queued failed requests in IndexedDB, coupled with logic in the main web page that checked IndexedDB for queued requests and retried any that it found.

var DB_NAME = 'shed-offline-session-updates';

function queueFailedSessionUpdateRequest(request) {
    simpleDB.open(DB_NAME).then(function(db) {
    db.set(request.url, request.method);
    });
}

function handleSessionUpdateRequest(request) {
    return global.fetch(request).then(function(response) {
    if (response.status >= 500) {
        return Response.error();
    }
    return response;
    }).catch(function() {
    queueFailedSessionUpdateRequest(request);
    });
}

toolbox.router.put('/(.+)api/v1/user/schedule/(.+)',
                    handleSessionUpdateRequest);
toolbox.router.delete('/(.+)api/v1/user/schedule/(.+)',
                        handleSessionUpdateRequest);

Because the retries were made from the context of the main page, we could be sure that they included a fresh set of user credentials. Once the retries succeeded, we displayed a message to let the user know that their previously queued updates had been applied.

simpleDB.open(QUEUED_SESSION_UPDATES_DB_NAME).then(function(db) {
    var replayPromises = [];
    return db.forEach(function(url, method) {
    var promise = IOWA.Request.xhrPromise(method, url, true).then(function() {
        return db.delete(url).then(function() {
        return true;
        });
    });
    replayPromises.push(promise);
    }).then(function() {
    if (replayPromises.length) {
        return Promise.all(replayPromises).then(function() {
        IOWA.Elements.Toast.showMessage(
            'My Schedule was updated with offline changes.');
        });
    }
    });
}).catch(function() {
    IOWA.Elements.Toast.showMessage(
    'Offline changes could not be applied to My Schedule.');
});

Offline Google Analytics #

In a similar vein, we implemented a handler to queue any failed Google Analytics requests and attempt to replay them later, when the network was hopefully available. With this approach, being offline doesn’t mean sacrificing the insights Google Analytics offers. We added the qt parameter to each queued request, set to the amount of time that had passed since the request was first attempted, to ensure that a proper event attribution time made it to the Google Analytics backend. Google Analytics officially supports values for qt of up to only 4 hours, so we made a best-effort attempt to replay those requests as soon as possible, each time the service worker started up.

var DB_NAME = 'offline-analytics';
var EXPIRATION_TIME_DELTA = 86400000;
var ORIGIN = /https?:\/\/((www|ssl)\.)?google-analytics\.com/;

function replayQueuedAnalyticsRequests() {
    simpleDB.open(DB_NAME).then(function(db) {
    db.forEach(function(url, originalTimestamp) {
        var timeDelta = Date.now() - originalTimestamp;
        var replayUrl = url + '&qt=' + timeDelta;
        fetch(replayUrl).then(function(response) {
        if (response.status >= 500) {
            return Response.error();
        }
        db.delete(url);
        }).catch(function(error) {
        if (timeDelta > EXPIRATION_TIME_DELTA) {
            db.delete(url);
        }
        });
    });
    });
}

function queueFailedAnalyticsRequest(request) {
    simpleDB.open(DB_NAME).then(function(db) {
    db.set(request.url, Date.now());
    });
}

function handleAnalyticsCollectionRequest(request) {
    return global.fetch(request).then(function(response) {
    if (response.status >= 500) {
        return Response.error();
    }
    return response;
    }).catch(function() {
    queueFailedAnalyticsRequest(request);
    });
}

toolbox.router.get('/collect',
                    handleAnalyticsCollectionRequest,
                    {origin: ORIGIN});
toolbox.router.get('/analytics.js',
                    toolbox.networkFirst,
                    {origin: ORIGIN});

replayQueuedAnalyticsRequests();

Push Notification Landing Pages #

Service workers didn’t just handle IOWA’s offline functionality—they also powered the push notifications that we used to notify users about updates to their bookmarked sessions. The landing page associated with those notifications displayed the updated session details. Those landing pages were already being cached as part of the overall site, so they already worked offline, but we needed to make sure that the session details on that page were up to date, even when viewed offline. To do that, we modified previously cached session metadata with the updates that triggered the push notification, and we stored the result in the cache. This up-to-date info will be used the next time the session details page is opened, whether that takes place online or offline.

caches.open(toolbox.options.cacheName).then(function(cache) {
    cache.match('api/v1/schedule').then(function(response) {
    if (response) {
        parseResponseJSON(response).then(function(schedule) {
        sessions.forEach(function(session) {
            schedule.sessions[session.id] = session;
        });
        cache.put('api/v1/schedule',
                    new Response(JSON.stringify(schedule)));
        });
    } else {
        toolbox.cache('api/v1/schedule');
    }
    });
});

Gotchas & Considerations #

Of course, no one works on a project of IOWA’s scale without running into a few gotchas. Here are some of the ones we ran into, and how we worked around them.

Stale Content #

Whenever you’re planning a caching strategy, whether implemented via service workers or with the standard browser cache, there’s a tradeoff between delivering resources as quickly as possible versus delivering the freshest resources. Via sw-precache, we implemented an aggressive cache-first strategy for our application’s shell, meaning our service worker would not check the network for updates before returning the HTML, JavaScript, and CSS on the page.

Fortunately, we were able to take advantage of service worker lifecycle events to detect when new content was available after the page had already loaded. When an updated service worker is detected, we display a toast message to the user letting them know that they should reload their page to see the newest content.

if (navigator.serviceWorker && navigator.serviceWorker.controller) {
    navigator.serviceWorker.controller.onstatechange = function(e) {
    if (e.target.state === 'redundant') {
        var tapHandler = function() {
        window.location.reload();
        };
        IOWA.Elements.Toast.showMessage(
        'Tap here or refresh the page for the latest content.',
        tapHandler);
    }
    };
}

The "latest content" toast.

Make Sure Static Content is Static! #

sw-precache uses an MD5 hash of local files’ contents, and only fetches resources whose hash has changed. This means that resources are available on the page almost immediately, but it also means that once something is cached, it’s going to stay cached until it’s assigned a new hash in an updated service worker script.

We ran into an issue with this behavior during I/O due to our backend needing to dynamically update the livestream YouTube video IDs for each day of the conference. Because the underlying template file was static and didn’t change, our service worker update flow wasn’t triggered, and what was meant to be a dynamic response from the server with updating YouTube videos ended up being the cached response for a number of users.

You can avoid this type of issue by making sure your web application is structured so that the shell is always static and can be safely precached, while any dynamic resources which modify the shell are loaded independently.

Cache-bust Your Precaching Requests #

When sw-precache makes requests for resources to precache, it uses those responses indefinitely as long as it thinks that the MD5 hash for the file hasn’t changed. This means that it’s particularly important to make sure that the response to the precaching request is a fresh one, and not returned from the browser’s HTTP cache. (Yes, fetch() requests made in a service worker can respond with data from the browser’s HTTP cache.)

To ensure that responses we precache are straight from the network and not the browser’s HTTP cache, sw-precache automatically appends a cache-busting query parameter to each URL it requests. If you’re not using sw-precache and you are making use of a cache-first response strategy, make sure that you do something similar in your own code!

A cleaner solution to cache-busting would be to set the cache mode of each Request used for precaching to reload, which will ensure that the response comes from the network. However, as of this writing, the cache mode option isn’t supported in Chrome.

Support for Logging In & Out #

IOWA allowed users to log in using their Google Accounts and update their customized event schedules, but that also meant that users might later log out. Caching personalized response data is obviously a tricky topic, and there’s not always a single right approach.

Since viewing your personal schedule, even when offline, was core to the IOWA experience, we decided that using cached data was appropriate. When a user signs out, we made sure to clear previously cached session data.

    self.addEventListener('message', function(event) {
      if (event.data === 'clear-cached-user-data') {
        caches.open(toolbox.options.cacheName).then(function(cache) {
          cache.keys().then(function(requests) {
            return requests.filter(function(request) {
              return request.url.indexOf('api/v1/user/') !== -1;
            });
          }).then(function(userDataRequests) {
            userDataRequests.forEach(function(userDataRequest) {
              cache.delete(userDataRequest);
            });
          });
        });
      }
    });

Watch Out for Extra Query Parameters! #

When a service worker checks for a cached response, it uses a request URL as the key. By default, the request URL must exactly match the URL used to store the cached response, including any query parameters in the search portion of the URL.

This ended up causing an issue for us during development, when we started using URL parameters to keep track of where our traffic was coming from. For example, we added the utm_source=notification parameter to URLs that were opened when clicking on one of our notifications, and used utm_source=web_app_manifest in the start_url for our web app manifest. URLs which previously matched cached responses were coming up as misses when those parameters were appended.

This is partially addressed by the ignoreSearch option which can be used when calling Cache.match(). Unfortunately, Chrome doesn't yet support ignoreSearch, and even if it did, it's an all-or-nothing behavior. What we needed was a way to ignore some URL query parameters while taking others that were meaningful into account.

We ended up extending sw-precache to strip out some query parameters before checking for a cache match, and allow developers to customize which parameters are ignored via the ignoreUrlParametersMatching option. Here's the underlying implementation:

function stripIgnoredUrlParameters(originalUrl, ignoredRegexes) {
    var url = new URL(originalUrl);

    url.search = url.search.slice(1)
    .split('&')
    .map(function(kv) {
        return kv.split('=');
    })
    .filter(function(kv) {
        return ignoredRegexes.every(function(ignoredRegex) {
        return !ignoredRegex.test(kv[0]);
        });
    })
    .map(function(kv) {
        return kv.join('=');
    })
    .join('&');

    return url.toString();
}

What This Means for You #

The service worker integration in the Google I/O Web App is likely the most complex, real-world usage that has been deployed to this point. We’re looking forward to the web developer community using the tools we created sw-precache and sw-toolbox as well as the techniques we’re describing to power your own web applications. Service workers are a progressive enhancement that you can start using today, and when used as part of a properly structured web app, the speed and offline benefits are significant for your users.

Jeff Posnick on web.dev

ES modules in service workers

Background #

Use cases #

Current limitations #

Static imports only #

What about other workers? #

No support for import maps #

Browser support #

Example code #

Backwards compatibility #

Handling range requests in a service worker

What's the issue? #

What's been fixed? #

Which browsers behave correctly? #

What about serving range requests from the cache? #

Handling navigation requests

Different approaches for architectures #

Small static sites #

Single-page apps #

Multi-page apps #

Everything else #

Adaptive loading with service workers

Production case #

Implement adaptive loading with Workbox #

Cloudinary Workbox Plugin #

Explore more adaptive loading strategies #

App shell UX with service workers and streams

Production case #

Implement an app shell UX architecture in MPAs with Workbox #

The server #

Partials #

The service worker #

Precaching static assets #

Streaming #

Instant navigation experiences

Production cases #

Implement precaching with Workbox #

1. Precache static pages and page subresources #

Precaching static pages #

Precaching page subresources #

2. Extend the lifetime of prefetch resources #

3. Delegate prefetching to the service worker #

Resilient search experiences

Production case #

Implement resilient search experiences with Workbox #

Conclusion #

Building resilient search experiences with Workbox

Measure #

Provide a fallback response #

Request notification permission #

Persist offline queries and retry when back online #

Test the feature #

Conclusion #

Preparing for AppCache removal

Timeline #

Origin trial #

Why are tokens needed in multiple places? #

Origin trial deployment timing and logistics #

Testing prior to removal #

Migration strategies #

Service workers and AppCache are mutually exclusive #

The cross-platform story #

Firefox on all platforms #

Safari on iOS and macOS #

Chrome on iOS #

Android WebViews #

Learn more #

Articles #

Tools #

Getting help #

Integrate PWAs into built-in sharing UIs with Workbox

On the same page #

Service worker share targets with Workbox #

Conclusion #

Keeping things fresh with stale-while-revalidate

What shipped? #

What's it mean? #

Live Example #

What are the common use cases? #

Appendix: `Cache-Control` flowchart #

Appendix: `Cache-Control` examples #