Enter an account below (your own, or someone else's), and get a sorted list of servers of the (first ~1000) accounts that it follows.

If you're building a progressive web app, and you're not exercising your service worker's behavior, you might have a gap in your overall test coverage. How high this ranks on the near-infinite list of things you could be testing depends on a number of things, including how important your service worker's behavior is to your core user experience.

If you're using Workbox, with mostly out-of-the-box default configuration options for your service worker's implementation, you might feel comfortable without a dedicated test suite, with the understanding that Workbox itself has an extensive set of tests for common usage patterns.

But if you're writing a service worker from scratch, if you're using one of Workbox's more exotic plugins or custom strategies, or if your service worker's behavior is particularly important to your overall user experience, developing a test suite dedicated to your service worker can give you an important peace of mind.

What kind of service workers are we talking about?

The service worker runtime environment has undergone an explosion of usage recently, with adaptations of the original environment spring up on the server, or in Manifest v3 extensions. This blog post discusses on tests that are important for "traditional" service-worker-in-the-browser use cases, focusing on caching and offline use cases.

What should I use to run my tests?

I recommend writing your tests against Microsoft's Playwright environment, though if you have an existing framework set up for integration/end-to-end testing, you can probably get away with using that instead.

I've found Playwright to be the best supported, most modern choice for running tests directly in "real" browser runtimes, across Chrome, Safari, and Firefox. While cross-browser compatibility for the service worker runtime is generally much better than it was in the past, if you're taking the time to test your service worker, you might as well ensure that there aren't edge cases due to, e.g., bugs in IndexedDB or reliance on service worker features that aren't yet in all three browser engines.

Some service worker tests might rely on, say, triggering a series of navigations and then checking cache state, and in my experience, Playwright has done a good job of orchestrating that type of behavior in a consistent fashion across browsers. This means fewer flaky tests, or tests that need to be skipped in specific browsers.

Throughout this post, I'll include inline examples that assume usage of Playwright.

Waiting for the right moment

A common pain point, leading to flakiness, retries, and awkward hardcoded calls to setTimeout(), is due to the asynchronous nature of most things having to do with service workers and the cache storage API. Throughout your test suite, you'll find yourself needing to delay execution of the next bit of code until some previous async operation has completed.

Here are a few scenarios where timing comes into play, along with tips on how to wait for the right moment.

Testing state after installation

A service worker might precache a set of URLs during installation, or add data to IndexedDB. To confirm that a given page registers a service worker which in turns performs those installation activities, it's important to delay examining the state until installation is complete. The simplest way to do this is to wait until the navigator.serviceWorker.ready promise resolves, at which point you're guaranteed that there is a service worker that's completed installation (and activation, though testing post-activation state is less common).

import {test, expect} from '@playwright/test';

test('post-install state', async ({baseURL, page}) => {
	// Navigate to a page which registers a service worker.
	await page.goto('/');

	// await the navigator.serviceWorker.ready promise.
	const swURL = await page.evaluate(async () => {
		const registration = await navigator.serviceWorker.ready;
		return registration.active?.scriptURL;
	});
	// Confirm the expected service worker script installed.
	expect(swURL).toBe(`${baseURL}sw.js`);

	// Now you're ready to check cache or IndexedDB state.
});

Testing network request interception

If you're interested in testing fetch handler behavior, i.e. how your service worker responds to network requests from a client page, waiting on navigator.serviceWorker.ready is not a good idea. That promise resolves as soon as there's an active service worker, but even if you're calling clients.claim() within your service worker's activate handler, there's a small gap of time before an active service worker takes control of existing clients. If you don't account for this, you may end up triggering a network request that isn't intercepted by your service worker, leading to tests that don't exercise the code you expect.

While there's no built-in equivalent to navigator.serviceWorker.ready that resolves when the current page is controlled by a service worker, you can explicitly create a promise that accomplishes the same thing.

import {test, expect} from '@playwright/test';

test('fetch handler behavior', async ({page}) => {
	// Navigate to a page which registers a service worker.
	await page.goto('/');

	// await a promise that resolves when the page is controlled.
	// Ensure you include clients.claim() in your activate handler!
	await page.evaluate(async () => {
		await new Promise((resolve) => {
			if (navigator.serviceWorker.controller) {
				// If we're already controlled, resolve immediately.
				resolve();
			} else {
				// Otherwise, resolve after controllerchange fires.
				navigator.serviceWorker.addEventListener('controllerchange', () =>
					resolve(),
				);
			}
		});
	});

	// Now calls to page.evaluate() which make network requests will
	// be intercepted by the service worker's fetch handler.
});

Testing logic outside of respondWith()

Every fetch handler needs to include fetchEvent.respondWith(). Once this method is called, response headers and a promise for the response body is made available to the controlled client that triggered the fetch event.

However, your fetch handler might perform other activities independent of the call to fetchEvent.respondWith()—for instance, cleaning up outdated cache entries after caching a new response. (If these activities are asynchronous, they would normally be wrapped in a call to fetchEvent.waitUntil() to ensure that the service worker is kept alive until they complete.)

Most developers won't have logic that executes in a fetch handler outside the fetchEvent.respondWith() that they need to test. But if you do find yourself needing to do so, be careful not to only wait on the client's fetch() that triggered the behavior to resolve. A client's fetch() will resolve immediately after the controlling service worker's fetch handler calls fetchEvent.respondWith(), and that might happen before the other asynchronous work is completed.

So, what do you do if you want to delay your test execution until after additional code has run? One solution is to have a client wait for a message event, triggered by the service worker calling postMessage() upon completion of the additional work. (Since this postMessage() is only useful for test orchestration, you might want to wrap it in an if() statement that checks for a specific process.env value, and is minimized away if that value isn't set.)

// Example service worker code:
self.addEventListener('fetch', (e) => {
  // When this executes, the client's fetch() promise resolves.
  e.respondWith(...);

  const additionalWork = async () => {
    // Perform cache cleanup, etc.
    const client = await clients.get(e.clientId);
    // Send a message back to the client to signal completion.
    client.postMessage({...});
  };
  e.waitUntil(additionalWork());
});

import {test, expect} from '@playwright/test';

test('extra fetch handler behavior', async ({page}) => {
	// Navigate to a page which registers a service worker.
	await page.goto('/');

	// await a promise that resolves when the page is controlled.
	// Ensure you include clients.claim() in your activate handler!
	await page.evaluate(async () => {
		const [message, response] = await Promise.all([
			new Promise((resolve) => {
				navigator.serviceWorker.addEventListener(
					'message',
					(e) => resolve(e.data),
					{once: true},
				);
			}),
			fetch('/url/to/test'),
		]);
		// Optionally do something to serialize response or message
		// and return it from the page.evaluate().
	});

	// Now the service worker's fetch handler has finished everything.
});

Cache expectations

In addition to the async-related nuances we just talked about, another stumbling block when writing service worker tests is how to ensure that a client's cache ends up in the expected state.

Getting the current global cache state

There's no cache storage API method that will return the full state of all caches in a single go. Additionally, the code that interrogates the cache will need to run inside of Playwright's page.evaluate() method, so only serializable values can be returned to the test() execution context—Request objects are used as cache storage keys, and they are not serializable. This means that getting the current cache state to use within an expect() assertion is a multi-step process.

import {test, expect} from '@playwright/test';

test('service worker install caching', async ({baseURL, page}) => {
	await page.goto('/');

	// Wait until the service worker has finished installing.
	const swURL = await page.evaluate(async () => {
		const registration = await navigator.serviceWorker.ready;
		return registration.active?.scriptURL;
	});
	expect(swURL).toBe(`${baseURL}sw.js`);

	const cacheContents = await page.evaluate(async () => {
		const cacheState = {};
		for (const cacheName of await caches.keys()) {
			const cache = await caches.open(cacheName);
			const reqs = await cache.keys();
			// Use the req.url string value, not an unserializable Request.
			// sort() allows the array to be used for stable comparisons.
			cacheState[cacheName] = reqs.map((req) => req.url).sort();
		}
		return cacheState;
	});

	// cacheContents now contains a mapping of cache names to an
	// sorted array of URL strings contained in the cache.
	expect(cacheContents).toEqual({
		'precache-v1': [
			`${baseURL}assets/app.js`,
			`${baseURL}assets/index.css`,
			// etc.
		],
	});
});

Comparisons of hashed URLs

Checking cache state using strict equality assertions can be a problem if your web app caches hashed URLs. While it's possible to update your test expectations every time any of your assets' contents change, you risk noise from failing tests if you ever forget.

A more flexible approach is to replace the hash portion of your URLs with a stable placeholder, and then compare those normalized URLs against strings that also use the same placeholder. Since I couldn't find an existing module that would accomplish this, and since I already had a different use case for the same functionality, I published the remove-filename-hash module to package up the reusable logic.

remove-filename-hash is flexible enough to deal with hashes using any character set, of any length, found anywhere in a URL or filename string. It works in any runtime environment that supports RegExp match indices.

Since a sample that illustrates the full cache comparison test is fairly long, you can take a look at a representative Playwright test on GitHub for inspiration.

Service worker update flow

Adding logic to your progressive web app to reacts to service worker updates can be a key part of a good user experience. However, triggering this logic in a test suite can be a challenge.

If you are running a custom HTTP server as part of your test suite, you can write runtime logic in that server that will respond with a slightly different version of your service worker JavaScript file each time it's requested—perhaps by appending a commented-out incremented counter to the end of the response. Any byte-for-byte difference between the current service worker file and the latest network response is sufficient to trigger the service worker update.

But if you're just using a static HTTP server, or if you'd prefer not to write custom server-side logic, your best bet for triggering a service worker update is to register two different service worker URLs sequentially.

Note: It's normally a best-practice to keep your service worker URL unchanged, but explicitly triggering an update is an exception to that.

Simulating an update

Here's an example of triggering a service worker update inside of a Playwright test; assume that the web page being tested already registers the service worker URL /sw.js, and that you have an updated service worker (potentially with different logic, if you'd like) available at /sw-updated.js.

import {test, expect} from '@playwright/test';

test('fetch handler behavior', async ({page}) => {
	// Navigate to a page which registers /sw.js
	await page.goto('/');

	// Ensure you include clients.claim() in your activate handler!
	await page.evaluate(async () => {
		// Wait until the initial /sw.js controls the page.
		await new Promise((resolve) => {
			if (navigator.serviceWorker.controller) {
				resolve();
			} else {
				navigator.serviceWorker.addEventListener(
					'controllerchange',
					() => resolve(),
					{once: true},
				);
			}
		});

		// At this point, you can set up listeners for whatever events/state
		// changes you care about waiting for, potentially creating new promises
		// (as with the above example) to confirm that they take place.
		navigator.serviceWorker.register('/sw-updated.js');
		// After calling register() with the updated URL, await the promises
		// you previously created to ensure that the changes happened.
	});

	// Any other test logic goes here.
});

This is a follow-up to my recent precaching vs. runtime caching post. I'd like to examine one of the advantages of precaching, as well as two of the disadvantages of runtime caching, and see if can make runtime caching more compelling by addressing them both.

Excerpting an advantage of precaching from my earlier blog post:

Allows you to "upgrade" from one version of cached subresources to another atomically. (Useful if, for instance, your templates and JavaScript rendering logic both need to be cached in concert with each other.)

And a disadvantage of runtime caching:

Assuming your URLs do include versioning information like hashes, there is no built-in mechanism for automatically expiring previous revisions of a given resource once a new one is in the cache. (I've been playing around with solutions via a Workbox plugin, though.)

(That last bit about the Workbox plugin is a spoiler for the rest of this post.)

So how can we use runtime caching and still get a reasonable best-effort coordination of cached resources without atomic cache upgrades? And how can we avoid cluttering up our runtime cache storage with dozens of versioned copies of the same logical assets, each with a different hash in their URL?

Naming conventions

All of the techniques in this blog post assume that you've adopted a consistent convention for translating "unversioned" filenames, like app.js, into a versioned equivalent containing a hash, like app.34abf34a.js or app.78dd13ee.js. If you're using a build tool that can do versioning, like Rollup or webpack, you're probably familiar with using the placeholder [hash] to specify where you want that hash inserted.

The exact tool you use to add these hashes doesn't matter as much as adopting a consistent naming format across all your URLs, with a fixed number of characters in the hash. We'll be writing code that will need to translate from a hashed URL to the underlying "unversioned" filename (i.e. app.34abf34a.js => app.js), so if you have the flexibility to do so, try to optimize your hash delimiters for ease of parsing.

For example, I've used the equivalent of [hash:8]~[name].[ext] for the versioned URLs on the current incarnation of my blog. An "unversioned" file named page.js might have a hashed filename of 8GlAOC2Y~page.js (I'm using base64url encoding for the hash, instead of hex, but that's an implementation detail.) I find it easier to extract the original name from the hashed filename if the hash is always at the start, and the ~ character offers a visual hint to anyone inspecting the URLs about where the hash ends.

Using this approach, translating a hashed URL into the original "unversioned" filename is as simple as taking the final portion of the URL's path and calling substring(), passing in the number of initial characters that need to be skipped.

Cleaning up old revisions

Now that we have a well-defined way to translate from a hashed URL to the corresponding original filename, there's a straightforward approach to ensuring that we don't indefinitely cache out of date versions of the same asset. The steps are:

• Find the "unversioned" filename for the URL that was just cached.
• Iterate through all the current cache keys, and find the "unversioned" filename for each.
• If the filenames match, delete the previously cached entry.

We're operating on the assumption that the newly cached hashed URL is the definitive version that should be kept around, and hopefully there isn't any other cache entries that refer to the soon-to-be-deleted hashed URL. (If there are, we'll cover how to handle that in the next section.)

Dealing with cache misses due to versioning

The other drawback of runtime caching to address is cache misses triggered by one resource referring to a outdated versioned URL of a subresource. You might encounter this if, for example, you cache HTML documents at runtime, and a user revisits a very old page that still refers to your CSS and JS files using hashes that have long since been purged from your servers and local caches.

This is a solved problem for precaching (usually! assuming you're careful about when you call skipWaiting()!), where you can deploy compatible versions of your HTML, JS, and CSS altogether, versioned alongside your service worker.

So how should you deal with it when using runtime caching? The answer is a little bit of ¯\_(ツ)_/¯ sprinkled in with some best-effort fallback logic.

Before implementing this, you should ask yourself whether you're actually comfortable using anything other than the exact version of a subresource that a page asks for. That answer might depend on what type of subresource is being requests—using an outdated CSS file or versioned image is likely to be a lot "safer" than using an old JS file containing crucial business logic. You should only adopt fallback logic when you're comfortable with that risk.

Assuming you are comfortable with falling back to a different version, being able to translate a versioned URL into the underlying logical resource makes things straightforward:

• Attempt to read the requested version of a given resource from some combination of the cache or network, depending on which runtime caching strategy you're using.
• If that fails for any reason, get the "unversioned" filename for the URL you're requesting.
• Iterate through all the cache keys, getting the "unversioned" filename of each entry.
• If there's a match, use that cached response to fulfill the original request.
• Otherwise, the request can't be fulfilled.

Packaging this up

I've been using this logic for my current service worker setup, packaged in a standalone Workbox plugin.

If you've never tried writing a Workbox plugin before, we've got some basic info in our docs, and I recorded a video for last year's Chrome Dev Summit with more examples:

The plugin takes advantage of the cachedResponseWillBeUsed, cacheDidUpdate, and handlerDidError strategy lifecycle methods to trigger all of the steps described above.

Why not officially release the plugin?

While I think the code in the plugin works as intended, I'm still not happy about the ergonomics of using it. Specifically, there's a lot of logic hardcoded in it related to the naming conventions that I'm using for my hashed URLs, and that won't work for sites that do something different, like include hashes in the middle of their filenames.

What's needed to clean this up a bit is to allow the plugin to take in a function that will translate from versioned filenames to unversioned, allowing folks to use this without requiring them to adopt a specific naming convention. My current usage assumes you can just do hashedFilename.substring(HASH_CHARS + 1), but folks might need to use a regular expression to obtain the original filename, or split on specific delimiter characters.

Update: I've released a standalone module, remove-filename-hash, that offers flexible removal of hashes from URLs.

In the meantime, feel free to borrow the code from that plugin and adapt the logic by hand to accommodate your current naming conventions.

Service workers and the Cache Storage API offer some very low-level primitives that developers are expected to build on top of. Some common recipes that work well are outlined in "The Offline Cookbook." Developers who want a higher-level package for those strategies often turn to the Workbox libraries. Generally speaking, Workbox divides up caching into two approaches.

There's precaching, where build tools (like workbox-cli or workbox-webpack-plugin) generate a manifest of URLs and revisions, which is then fed into the workbox-precaching runtime module. Based on the precache manifest, workbox-precaching keeps your cache up to date and sets up a route to serve precached URLs using a cache-first strategy.

There's also runtime caching, where you use a mix of workbox-routing and workbox-strategies (along with any plugins).

Workbox will let you go all-in on either precaching of runtime caching, if you want, but you can also use both types of caching within the same service worker. (If you do, the order in which you register routes is imports; your should include precacheAndRoute() before any additional registerRoute() statements to ensure that anything in your precache manifest ends up being served via the precache strategy!)

In order to help developers decide which URLs should be precached and which should be runtime cached, here's a rough rundown of pros and cons of each approach. We'll formalize this information as part of an upcoming, long-overdue revamp of the Workbox documentation, but I recently wrote this up for a different purpose, so I figured I'd make it public!

Precaching Pros

• Cache-first is "safe" with URLs that don't contain hashes, since the revision information is generated at build time and maintained out-of-band in the precache manifest.
• Allows you to "upgrade" from one version of cached subresources to another atomically. (Useful if, for instance, your templates and JavaScript rendering logic both need to be cached in concert with each other.)
• You can easily cache resources that are needed for subsequent pages, instead of waiting for the service worker to take control and intercept the request for runtime caching. (You can work around this somewhat by explicitly adding items to a runtime cache.)

Precaching Cons

• Requires a build step.
• Unconditionally caches everything during service worker installation. If you include URLs for infrequently used subresources in the precache manifest, or large resources like images, that can be wasteful, as you're caching things that will never be read.
• Precaching resources that update frequently can lead to a lot of "cache churn". This is fine for subresources that are commonly used, but the worst case scenario is that you've precached an infrequently used subresource that's updated frequently, compounding the wasted bytes described in the previous point.

Runtime Caching Pros

• Works well for URLs whose hash can't be determined at build time. (This is an issue for most dynamic or server-rendered content.)
• Flexibility to use either a network-first or cache-first strategy, giving you control over the freshness vs. speed tradeoff.
• Allows the cache lifetimes of different subresources to exist independent of each other, based on routing rules, and cache expiration plugins.

Runtime Caching Cons

• Users might end up with a broken offline experience if the page relies on resources that haven't been cached yet.
• If a given URL doesn't include hash or versioning info, it's generally not safe to use a cache-first strategy. The best your can do is stale-while-revalidate, to ensure that the cached resources gets updated eventually.
• There are no atomic updates of cached resources. One JavaScript subresource may have been updated recently via a stale-while-revalidate strategy, while your templates weren't, and that can lead to a mismatch or incorrect assumption about interoperability.
• Assuming your URLs do include versioning information like hashes, there is no built-in mechanism for automatically expiring previous revisions of a given resource once a new one is in the cache. (I've been playing around with solutions via a Workbox plugin, though.)

Takeaways

My normal go-to is to precache as much as possible, as most of my web apps have a build process already, they normally are limited in size (say, under 1 megabyte for all of the app content), and I don't churn my cached resources that frequently. Whenever I do mix in runtime caching, it's normally for things that can't be versioned at build time (like live API results) or for images, which I'd rather not force everyone to download during service worker installation.

During my recent blog infrastructure rewrite, though, I've ended up going entirely with runtime caching, instead of precaching. I don't know if there's a technical reason for that choice as much as giving me an opportunity to experience some of the pain points that come with runtime caching, like how to expire old versions of hashed URLs.

Continued blog infra rewrite

I had a lot of fun getting full service worker rendering working for this blog, and have continued to noodle on a number of improvements since then.

Some of them are bigger than others (I'm looking forward to writing a dedicated post about the Workbox plugin I built that improves runtime caching for hashed URLs!), but a quick one is a plug for the @digitak/esrun module.

esbuild is great at build time

I've been very happy using esbuild extensively in my blog's build process. It's provided (almost) zero-config TypeScript transpilation and bundling that runs so much faster that others tool with similar feature sets.

One thing that bothered me, though, was that my build scripts produce a number of assets that are consumed at runtime by my HTML and JavaScript, but because my build process didn't understand TypeScript types, I didn't have a lot of confidence that all the data structures matched up, and that if I refactored code in one place, I'd remember to update my generated assets.

Writing my build scripts in TypeScript would solve that, but adding in another build step to transpile my scripts before I could start my real build process sounded clunky. I know that ts-node and a few other options have been around for a while, but I haven't heard great things about their speed.

esrun is great at runtime

Some more Googling led me to @digitak/esrun, which is a light wrapper on top of esbuild that will automatically transpile TypeScript source files before running them as command line scripts.

After adding @digitak/esrun to devDependencies, and rewriting my build scripts in TypeScript, my package.json's build script went from

{
	"scripts": {
		"build": "node src/build/main.js"
	}
}

to

{
	"scripts": {
		"build": "esrun src/build/main.ts"
	}
}

That's all it took! I now have confidence that comes from sharing types between my build and runtime environments, and the increase in build time due to transpilation is completely negligible.

tl;dr

This site is now rendered entirely on-demand via service workers!

The first time you visit, you'll get HTML rendered in the cloud using Cloudflare Workers. For each subsequent page you visit, a local in-browser service worker generates equivalent HTML, taking advantage of local caching to render as much HTML as possible without blocking on the network.

Both service worker environments share the majority of the same Workbox code for routing and streaming response generation.

You can see everything that changed from my previous setup in this diff.

Previously, on blog infra

This site previously used a custom 11ty setup, with static HTML generated at build time, using Nunjucks templates and Markdown pages. (It was migrated from a long-ago Jekyll config.)

After your first visit, a Workbox-powered service worker took over, and cached all of the templates and page data. HTML for future navigations are generated by the SW, independent of the network, using the same templating logic that 11ty uses at build time.

The templates were cached independently from the page content, so I could, e.g., update the site header template, and that's the only thing that needs to be invalidated—already cached content could stay as-is.

It was served from Firebase static hosting.

This all worked well!

But, the disconnect between how 11ty and the service worker generated the HTML bothered me. They shared templates, but static HTML "routing" happens via file system layout, while the service worker needed its own independent routing configuration. Also, running Nunjucks inside of a service worker works, but it's not exactly elegant, or lightweight. And generating the site's full HTML at build time is fine for a site with a modest amount of content, but I could see it being an issue for larger sites, or for sites that rely on database or API lookups to populate their HTML.

Service workers everywhere

I've been fascinated by the new crop of cloud runtime environments that expose a service worker API (or some modified version of it). Cloudflare Workers seems like the most mature of them, and it looks like the recently formed Deno Company is working on something similar. Running the service worker API in the cloud opens the door for a closer sharing routing and HTML generation logic with the browser's service worker—isomorphic rendering, if you will. (It's cool if you won't.)

A recent tweet from Luke Edwards about his new, lightweight Handlebars-compatible templating library, Tempura, reminded me that Luke was now working on the Cloudflare DevRel team, and that I have been intending to explore this space further.

Well, no time like this weekend!

Build setup

Some of the work involved swapping out the 11ty build infrastructure in favor of a bespoke build process. At some point I might re-add 11ty, because I ultimately think that I just ended up recreating most of what it already does. But while prototyping this, I needed the level of control offered by generating exactly the build artifacts I wanted from my source Markdown files.

The nice thing is that, for the most part, my existing posts didn't need to change—they remain Markdown documents with some frontmatter metadata, just like 11ty (and before that, Jekyll) expected.

Shared service worker code

Most of the magic takes place in the shared service worker code, which handles routing using a wrapper on top of the upcoming URLPattern API, along with some logic to handle requests for static assets like images, CSS, JS, or JSON files.

Streaming, sequential templates

Each matching route triggers a sequence of Tempura templates, with each rendered template streaming its partial HTML immediately in environments that support constructing ReadableStreams, courtesy of the workbox-streams library.

Here's an adapted snippet of code:

registerRoute(
	new URLPatternMatcher({pathname: '/(.*).html'}).matcher,
	streamingStrategy(
		[
			() => Templates.Start({site}),

			async ({event, params}) => {
				const post = params.pathname.groups[0];
				const response = await loadStatic(event, `/static/${post}.json`);
				if (response?.ok) {
					const json = await response.json();
					return Templates.Page({site, ...json});
				}
				return Templates.Error({site});
			},

			() => Templates.End({site}),
		],
		{'content-type': 'text/html'},
	),
);

This initial HTML response always comes from the first template immediately, without blocking on any data retrieval, so you should see consistently fast renders of each page's header. What's displayed right away is roughly equivalent to what you'd see if you were using an App Shell.

Unlike with an App Shell approach, it's easy to set up a completely different sequence of templates for different routes. You're not forced to always respond with a single, hardcoded placeholder HTML document.

Different approaches to static assets

The some significant difference between the CloudFlare and browser service workers is how they load static assets.

The CloudFlare Workers runtime supports loading static assets via a kv-asset-handler helper library.

Here's an abbreviated snippet of that code:

const loadStatic = async (event, urlOverride) => {
	const options = urlOverride
		? {
				mapRequestToAsset: (request: Request) => {
					const absoluteURLString = new URL(urlOverride, request.url).href;
					return mapRequestToAsset(new Request(absoluteURLString, request));
				},
		  }
		: {};

	return await getAssetFromKV(event, options);
};

The browser runtime relies on Workbox's caching and routing to load those assets. A stale-while-revalidate strategy ensures that the service worker can render all the content quickly if you've previously visited the same page.

Workbox's BroadcastUpdatePlugin will notify any open window clients when an update is found for cached content during the revalidate step. I took the blunt-force approach of reloading the entire page when this happens, but a more nuanced approach would involve showing a message on the screen, prompting the user to reload if they would like to see new content.

You end up with code like:

const swrStrategy = new StaleWhileRevalidate({
	cacheName: 'static',
	plugins: [new BroadcastUpdatePlugin()],
});

const loadStatic = async (event, urlOverride) => {
	return await swrStrategy.handle({
		event,
		request: urlOverride || event.request.url,
	});
};

An alternative would be to use Workbox's build tools to generate a precache manifest of all the JSON files needed to render every page on the site. (This is what I've done with previous iterations of this blog.) I decided to go with runtime caching approach instead, in the interest of minimizing the amount of data transferred during service worker installation. This means that you can't navigate to every page on this blog while offline—only to the pages you've previously visited. If making the entirety of your site work offline after the first visit is important to your use case, precaching everything will let you do that!

What's next?

Unlike some of my previous efforts in this space, I'm pretty confident that this setup isn't too out there. It seems like web developers are comfortable with embracing service workers in the cloud, and Workbox has been going strong for over six years now.

Moreover, while I implemented this architecture on blog site with Markdown files, this same approach could apply equally well to a site that relied on database or API calls to populate each page's content. The only thing that needs to change is the logic that retrieves data to populate each page's template. And because that logic only needs to be written in one place, inside the shared service worker code, you don't have to worry about it getting out of sync between the cloud and browser.

I'm excited to see if more folks use my current setup as inspiration, and am happy to chat with anyone interested in turning this into a reusable started kit!

But while Apps Script has come a long way, and features lots of ES2015+ goodness nowadays, it's not possible to pull in arbitrary code from npm and run it directly.

To work around this, I created the following index.js file locally, exporting the interface that I wanted to call from Apps Script:

import psl from 'psl';
import Url from 'url-parse';

export function parseHostname(sourceURL) {
	const url = new Url(sourceURL);
	return psl.parse(url.hostname);
}

Then, I installed the necessary dependencies from npm, and bundled this code up with esbuild:

npm init -y
npm install --save-dev psl url-parse punycode
npx esbuild index.js --bundle --global-name=psl --outfile=psl.js

I manually copied the contents of the psl.js file into a psl.gs file, alongside my main Code.gs file in the Apps Script editor. (This would be annoying if the bundled output changed frequently, but doing it once by hand wasn't a problem.)

Apps Script will automatically make the contents of all .gs files in a project visible in the same global scope, so I could now write code like

const {sld} = psl.parseHostname(url);

inside of my main Code.gs file.

Caveats

The Apps Script runtime environment still has a bunch of quirks when compared to Node, so don't expect all of your bundled code to work as-is. Polyfills may be needed (I used url-parse, for instance, since the native URL object isn't available in Apps Script.)

Once you copy over the bundled code to Apps Script, it's never going to be updated, so make sure you're prepared to rebundle if and when there are any security or feature updates to the modules you're using.

Chrome DevTools has supported conditional breakpoints since, at least, July of 2015, but I'm embarrassed to admit that I've never tried them until now.

Service worker debugging

I found myself (as I often do...) trying to track down exactly why a service worker was behaving in a certain way when processing incoming requests in its fetch handler(s). If this were code for my own project, I'd (no judgment!) throw in a ton of console.log() statements and make sense of what got spit out on the Console after redeploying. But since I was looking at someone else's code, that debugging technique wasn't feasible. (Well, actually it is, but I needed something more powerful and less noisy than a bunch of logging.)

Instead, I remembered that conditional breakpoints could be set at runtime, and decided to give them try.

What to look for, and break on

In this case, I wanted to start debugging at the very start of a fetch event handler, but only if the handler were processing an incoming request for a specific type of URL. I was dealing with code generated by Workbox, and it was minimized, so finding the exact place to start debugging was a bit of a challenge.

Taking DevTools up on its offer to pretty-print the source code was the first step:

Next, I searched the source code for the string fetch. Even though most of the symbols were minimized, string constants like addEventListener('fetch', ...) were still intact, so finding that is reliable.

Once I found the right spot, I right-clicked on the line number where I wanted to conditionally enter the debugger:

There were a lot of different requests being made, but I knew that the one I cared about had a URL containing common. I also knew that even through the variable was renamed to e during minification, the parameter passed to a fetch event listener is a FetchEvent. That, in turn has a request, and that has a url property string. So e.request.url would give me access to a URL that I could conditionally match:

If I were trying to debug something different, like tracing the logic used for all image requests, I could use different properties of the Request, leading to a condition like e.request.destination === 'image'.

Note

In this particular case, there were actually two fetch event handlers, which is a valid thing to have! This is an implementation detail that might change in the future, but Workbox currently creates one for its precache logic, and one for its runtime logic. So what I actually had to do was assign conditional breakpoints inside both of those handlers to figure out which one was running.

webpack is preparing its v5.0.0 release, and as the maintainer of the workbox-webpack-plugin, I want to make sure we work well with the new version. But at the same time, we can't abandon compatibility with webpack v4.x.

We've got an extensive test suite that previously assumed there would be a single version of webpack that we tested against, so how can we make sure that we can run our individual tests against multiple versions of webpack, without modifying any of the require('webpack') statements in workbox-webpack-plugin? (The same applies other plugins that are exercised alongside workbox-webpack-plugin in our test suite, like html-webpack-plugin.)

The solution

Step 1: Install multiple package versions

npm v6.9.0 added support for package aliases. This allows you to install multiple versions of the same npm package under different node_modules/ subdirectory names.

In my case, I ran:

npm install --save-dev webpack-v4@npm:webpack
npm install --save-dev webpack-v5@npm:webpack@5.0.0-rc.3

After running that, my package.json included:

"devDependencies": {
  "webpack-v4": "npm:webpack@^4.44.2",
  "webpack-v5": "npm:webpack@^5.0.0-rc.3"
}

and I had local node_modules/webpack-v4/ and node_modules/webpack-v5/ directories.

Step 2: Use module-alias to override require()

module-alias makes overriding require() behavior extremely easy. I was worried that I would need to start modifying the NODE_PATH environment variable or something like that, but module-alias is all you need.

Here's an approximation of how I used it:

const path = require('path');
require('module-alias').addAlias(
	// Replace with the "real" name of the module.
	'webpack',
	// Replace with the actual local versioned directory path.
	path.resolve('node_modules', 'webpack-v4'),
);

This aliasing will be in effect for a require() that's performed in any submodules as well, for the lifetime of the process. If you need to clear it out at any point before the process exits, you can use:

// Replace with the name of the module you're aliasing.
delete require.cache[require.resolve('webpack')];

Solution in context

This PR includes the full set of changes that I made for webpack v5 compatibility, including the dependency changes described above.

Thanks

Huge thanks to Jason, for walking me through this solution. I wanted to get this all written up somewhere permanent in case others have the same problem.

My teammate Alan's been running a weekly livestream on his YouTube channel, focusing on topics of interest to eCommerce websites. He asked me to come on this week and perform a site performance audit.

Since I'm currently homebound due to Coronavirus concerns in NYC, I haven't had the chance to perform any in-person site audits in a while. Going through the process via a livestream was a great opportunity!

The site review

The review process took about 50 minutes (I'd recommend watching at 2x playback speed...) and covered some relevant findings from WebPageTest.org and Lighthouse.

We choose the site, https://threddies.com/, "at random" based on folks who volunteered. I think it ended up being fairly representative of the types of issues a lot of sites encounter.

Lightly edited from the notes I took during the review.

Tools used:

• "Easy" mode on WebPageTest (site results)
• Lighthouse

Observations

• 11 seconds for main content to load — what's loaded beforehand?
• How many of the widgets/analytics tools can be lazily-loaded (or potentially removed, if appropriate)?
• HTTP cache expiration best practices.
• Use the Coverage panel in Chrome Dev Tools to evaluate how much of your JS/CSS in the critical request path is being used
• Q: Can they get away with loading Google Maps static images instead of Google Maps widget? Answer: yes, they can.
• Always click on the "Learn More" link in Lighthouse for additional context!
• Zach Leatherman's guides to loading web fonts are great.

The concept of CORS requests comes up a lot in my professional life. Much of the time, it's in the context of why a given response is opaque, and how to make that response non-opaque so that it plays nicely with service workers and the Cache Storage API.

Fortunately, many popular third-party APIs and hosts support CORS nowadays, and solving your basic CORS-related mystery normally boils down to, say, adding in the crossorigin attribute to your <img> tags.

When CORS is not enough

But while enabling CORS is enough to get back basic information about an HTTP response—like its status code, or access to its body—there's still some information that's locked down by default. The headers exposed on a CORS response, for instance, are limited to the following six "simple" response headers:

• Cache-Control
• Content-Language
• Content-Type
• Expires
• Last-Modified
• Pragma

Some of those headers can come in handy when accessed inside of a service worker, but there's one in particular that can be useful, but isn't exposed by default: Date.

In particular, if you're using Workbox's cache expiration logic and you provide a maxAgeSeconds parameter, the Date of the cached response is checked against the difference between the current time and maxAgeSeconds. If the Date is too old, then the cached response will end up being ignored.

But... this logic only works if there's a Date header exposed on the response. By default, that won't be the case for a CORS response.

Exposition

The workaround, as with so many things related to CORS, involves fiddling with HTTP response headers. You'll either need access to the underlying HTTP server yourself, or you'll need to reach out to your CDN/API provider asking them to make the change.

Setting Access-Control-Expose-Headers: Date will permit the Date response header to be visible to your web app's code, and you could include any additional headers there in a comma-separated list.

If you're using your own Express-based web server, the corser middleware looks pretty reasonable for setting up a working configuration. Their docs include a recipe for configuring the exposed response headers.

Live demo

Here's a quick demonstration, separate from service workers, and using the fantastic https://httpbin.org service to control the Access-Control-Expose-Headers response header that's returned in a simulated API response. (They support CORS by default, so nothing needs to be done to enable that.)

Check out the log messages in the JavaScript console to see which headers are visible in the response.

Without Access-Control-Expose-Headers: Date

With Access-Control-Expose-Headers: Date

I moved over to work on Google's Web DevRel team way back in 2014, and one of the first tasks that I took on was writing short update articles and code samples for new web platform features. These are... somewhat embarrassing to look back on, so I won't link to many here, but one of the first I put together covered generators. I didn't have a huge amount to say about generators, so the general approach used in the article was to link to some more canonical resources, while calling out a couple of interesting "gotchas" that I thought could add some value.

So I wrote that, moved on, and then pretty much forgot that generators existed for the next 4 years.

Refactoring

That takes us to a few months ago, when I was working on a rewrite of the workbox-precaching module as part of the Workbox v4 release. This gave me an opportunity to revisit some code that hadn't been touched in a while.

Original logic

The actual code isn't super-relevant (I'll link to the before and after below, for those who are interested), but the main points were:

• It was code to compare a string against few possible matches.
• Calculating each possible match is (somewhat) expensive.
• The code returned true as soon as it found a match.
• If none of the conditions matched, it returned false.

The original code looked something like:

const originalUrl = '...';
const urlToMatch = '...';

const urlVariation1 = generateVariation1(originalUrl);
if (urlToMatch === urlVariation1) {
	return true;
}

const urlVariation2 = generateVariation2(originalUrl);
if (urlToMatch === urlVariation2) {
	return true;
}

// etc.

return false;

I'm not a huge fan of a repeated sequence of if(...) { return ... } statements aesthetically, and structuring code like that can make it harder to understand that each test case is effectively doing the same thing.

Refactoring without generators

One potential refactoring to emphasize the repeated logic could be:

const originalUrl = '...';
const urlToMatch = '...';

const urlVariations = [
	generateVariation1,
	generateVariation2,
	// etc.
].map((generateVariation) => generateVariation(originalUrl));

for (const urlVariation of urlVariations) {
	if (urlToMatch === urlVariation) {
		return true;
	}
}

return false;

I like that version of the code from an aesthetic point of view, but one downside is that you end up running each of the generateVariationN() functions ahead of time. If a variation early in the list ends up matching, you've ended up running (potentially expensive) code for nothing.

Refactoring with generators

So! This is when I remembered that generators were A Thing, and could come in handy in this use case.

Generators are iterable, so it could be dropped right in to a for...of loop.

Generators only run when their next() value is requested: they'll execute until a yield keyword is encountered, at which point they pause and control goes back to whatever triggered the iteration. If we yield the results of our potentially expensive functions one at a time inside of a generator, we don't have to worry about executing functions whose results won't actually be needed. And we still get to structure the code that uses the values as a loop rather than a sequence of if(...) { return ...; } statements. It's the best of both worlds!

Using a generator and a for...of loop gives us code that looks something like:

function* generateVariations(originalUrl) {
	// You could put these yields inside a loop, too!
	yield generateVariation1(originalUrl);
	yield generateVariation2(originalUrl);
	// etc.
}

for (const urlVariation of generateVariations(originalUrl)) {
	if (urlToMatch === urlVariation) {
		return true;
	}
}

return false;

The actual changes in Workbox

If you're curious, the original code in Workbox v3 is here. The v4 code has been split up into modules for the new generator and the code that loops over the generated values.

Here's a rather contrived example of how you could use CSS to make certain <script> tags visible, and use <details> + <summary> to hide them by default.

Here's my thinking:

These are all equally valid end-states, based on the tradeoffs that make sense for each developers' use case:

1) Precache HTML in a SW, and get the benefits of navigation being reliably fast.

1a) Use skipWaiting: false to ensure that precached assets are updated eventually, once all the existing tabs controlled by the old SW are closed. A recipe like this one, which could ideally be added to c-r-a, can make this a better UX.

1b) Use skipWaiting: true to ensure that precached assets are updated immediately, with the understanding that this can mess up lazy-loading. (Maybe you already have fallback logic to deal with flaky lazy loading.)

2) Use a SW that doesn't precache your HTML, but potentially offers some other benefits, like runtime caching of subresources, or displays a custom "you're offline" web page.

3) Don't use a SW at all.

Ideally developers would have the flexibility to choose which state to be in. The SW integration in c-r-a is tricky, because the configuration is (for obviously valid reasons) locked down to the points where choosing being those options is non-trivial. That makes it important to ship with the right default behavior, one that will strike a balance between providing benefits to the user with minimal negative side effects.

c-r-a v1 shipped with 1b) by default, with the only "escape hatch" to change some runtime code and avoid registering a SW. In retrospect, that wasn't a great default.

c-r-a v2 shipped with 3) by default, with developers who explicitly opt-in ending up in 1a). I think that's a saner/safer default, but it might not be the right fit for all developers.

2) is interesting, and I don't want to say that that kind of SW is inappropriate. It's just that it really requires a level of SW configuration that you can't default to in a locked-down environment like c-r-a.

If developers have the ability to configure Workbox without needing to eject, I think they'll have the tools they need to choose any of those end states.

I haven't done a great job of updating the c-r-a docs to explain all that, and that's on me to take care of. (Update: here's a PR that will hopefully help.)

Following up from my "Beyond SPAs: alternative architectures for your PWA" talk at Google I/O this year, I've been investigating ways of bringing all of the benefits folks associate with PWAs (network-independent loading, rich metadata provided by a web app manifest) to a more traditional, "blog-y" site architecture.

Mathias was visiting NYC last week, and I gave him some advice about the service worker for the relaunched V8 developer blog. He ended up going with 11ty for building the blog, along with Nunjucks templates. I figured it was worth giving that set of tools a try, and see what migrating my existing, Jekyll (+ Liquid templates) blog setup would be.

And, while I was at it, I wanted to see what it would look like to implement all of the site build + templating infrastructure inside of a service worker, to give a more robust offline-first experience than what Mathias was able to get for the V8 blog. (Just the index page was being cached.)

The present

I've moved most of the templates over to use Nunjucks, though I believe I've lost a few filters and date formatting options that I had with Liquid.

Using 11ty instead of Jekyll to orchestrate the build was very straightforward, after moving a few directories around.

I've created a helper script to take care of the service worker metadata generation. This basically handles a lot of the same processing that 11ty does as part of a build, but spits out the data in JSON files that could then be cached and read from the service worker using the Cache Storage API.

The service worker itself, not surprisingly, uses Workbox under the hood for precaching and runtime caching, with a custom handlerCallback to trigger the Nunjucks rendering.

Nunjucks rendering worked very well—there's an official build of Nunjucks which runs in the browser (including in a service worker), and that really made it much easier to set this up. I've struggled in the past to implement service worker templating using libraries that weren't really meant to run in the browser, or did not have pluggable loaders (to pull in templates using the Cache Storage API). Wrapping callback-style asynchronicity with promises meant that everything played nicely. I would love to see if, in the future, Nunjucks could be replaced by something a bit more lightweight—perhaps native JavaScript template literals.

Check out the latest deployed version of this site's service worker if you want to learn more—I'm expecting to clean it up quite a bit as I find some more time. One pretty neat bit worth excerpting is:

const postHandler = async ({params}) => {
	const site = await initSiteData();
	const cachedResponse = await caches.match(
		`/_posts/${params.join('-')}.json`,
		{
			cacheName: workbox.core.cacheNames.precache,
		},
	);
	const context = await cachedResponse.json();
	context.site = site;
	context.content = context.html;
	const html = await new Promise((resolve, reject) => {
		nunjucksEnv.render(context.layout, context, (error, html) => {
			if (error) {
				return reject(error);
			}
			return resolve(html);
		});
	});
	const headers = {'content-type': 'text/html'};
	return new Response(html, {headers});
};

workbox.routing.registerRoute(
	new RegExp('/(\\d{4})/(\\d{2})/(\\d{2})/(.+)\\.html'),
	postHandler,
);

Caching strategies

All of the site metadata, templates and content (a whole 8 blog posts!) are precached, which adds up to only ~77kb for my blog. If I were working on a larger site, I'd consider only precaching the site metadata and templates, and using a runtime caching strategy for the posts' JSON.

I've got a cache-first strategy set up for the few images that I use on this blog.

After the service worker's installed, subsequent navigations should be fulfilled entirely from the cache, making the site work fully offline and, more importantly, load reliably fast. (The fact that it's all just some ugly static HTML and CSS helps with the speed, too.)

The future

I'd love to get some of the logic that I've put into the custom build scripts into the core of the 11ty project, if that makes sense, or at least packaged up into a standalone set of helpers.

I need to refactor a bunch of that code to stop hardcoding things like paths, as well as try to support custom 11ty filters and plugins within the service worker.

As mentioned, I'm still evaluating whether Nunjucks is the right templating engine to use, but its syntax does seem familiar enough for folks coming from Liquid templates, or Jinja.

The actual service worker code needs to be refactored a bit, and I'd like to make it flexible enough to load any _data you're using, not just the site.json.

I'm not minimizing anything right now, and the build process is generally a bunch of things stuck together with tap.

Alternatives

There are a host of other options for folks to consider right now—it's actually a really great time for PWA-y static blogs and site generators. I like what Gatsby's doing, especially with v2 (featuring Workbox-powered offline support). Vuepress is similarly vue-pressive, and features Workbox integration as well.

But if you're not interested in building your site's structure using React or Vue, and are coming from a more Jekyll-y starting point, I'm kind of excited about the approach I'm using here.

Chrome Dev Summit 2017 is behind us. I spent most of the run-up to the event putting together my "Workbox: Flexible PWA Libraries" talk, but beyond that, I was also involved in running on-site Performance Review Clinics that attendees could sign up for.

It's always a privilege to meet with the developers who are building web apps that I use every day, and to lend whatever guidance I could offer. Looking into the performance of a large group of production websites gives insights that you wouldn't get from just examining a site as a one-off. Patterns start to emerge about common areas for improvement.

I wanted to publicly share a few high-level groupings based on those patterns, and identify a handful of links for each area that contain useful guidance. It's by no means exhaustive, but I can say that each of these links contains solutions to a real-world performance issue that we identified during the Performance Review Clinics.

Linkdump!

Huge thanks go out to all the authors, many of whom I'm lucky enough to work with.

Overall Migration/End to End Case Study

• A React And Preact Progressive Web App Performance Case Study: Treebo

Loading and Prioritization

• Introduction to HTTP/2
• Resource Prioritization – Getting the Browser to Help You
• Deep dive into the murky waters of script loading

JavaScript

• Can You Afford It?: Real-world Web Performance Budgets
• JavaScript Start-up Performance

CSS

• critical: Extract & Inline Critical-path CSS in HTML pages
• The future of loading CSS
• loadCss: A function for loading CSS asynchronously

Caching

• HTTP Caching
• Caching best practices & max-age gotchas
• Service Workers: an Introduction
• Workbox: JavaScript libraries for Progressive Web Apps

Images/Multimedia Content

• Essential Image Optimization
• Lazy Loading Images Using Intersection Observer
• Inline SVG vs Icon Fonts [CAGEMATCH]
• Content Jumping (and How To Avoid It)
• A Better Method for Embedding YouTube Videos on your Website

Background

As I detaileda few years ago when I started up this blog, I used a combination of GitHub Pages + Cloudflare for a basic HTTPS static site deployment, pointed at by the jeffy.info domain I bought from Google Domains.

I'd be meaning to try something different for a while now, since

• I'm not taking advantage of GitHub Page's automatic Jekyll build anymore (relying instead on a custom build process that, among other things, generates a service worker for this site).
• I'm not happy about the lack of control GitHub Pages offers over HTTP caching, in which everything is served with a max-age of 10 minutes. I really wanted to serve my /service-worker.js with HTTP caching disabled entirely.
• After experimenting with some of the various rewrites and optimizations that Cloudflare's proxy servers could perform, I'd turned all of them off, preferring instead to take any steps needed to minimize resources during the build process.

For whatever reason, last night seemed like a good night to actually switch to something else.

Migrating to Firebase Hosting

I work with the folks responsible for Firebase Hosting, so I won't pretend that this was an unbiased decision, but I'm quite glad that I decided to switch things over to them.

Deploying to jeffy-info.firebaseapp.com

The first step was getting my site deployed to a subdomain under firebaseapp.com, to make sure that everything looked okay there. Given that I just was serving the entirety of a static build/ folder, this was low-drama. A basic firebase.json configuration was enough to specify my public build/ directory, and also configure the cache policy I wanted for /service-worker.js at the same time:

{
	"hosting": {
		"public": "build",
		"headers": [
			{
				"source": "/service-worker.js",
				"headers": [
					{
						"key": "Cache-Control",
						"value": "no-cache"
					}
				]
			}
		]
	}
}

Things looked fine when deployed to jeffy-info.firebaseapp.com, so the next step was to switch over the DNS entries for jeffy.info to point to Firebase Hosting's IP addresses, and wait for Firebase Hosting to generate a new HTTPS certificate for me.

Configuring Google Domains DNS

This was arguably the hardest part of the migration, primarily because it's a change that might take up to an hour (or whatever the previous DNS TTL was) to go into effect. During that interval things might look broken in several different ways. But patience was called for, and things just started working once the DNS configuration changes and new certificate went into affect.

Assuming you're using Firebase Hosting + Google Domains, the relevant bits to look for are switching the Name Servers back to use Google's defaults, like so:

And then also adding in an A record for the @ entry, with the IP addresses provided by Firebase Hosting:

Let's Encrypt FTW

One of the original reasons I went with a Cloudflare proxy in front of my GitHub Pages deployment was because it was a simple way to get an HTTPS certificate for a custom domain. It's 2017 and Let's Encrypt is very much a thing, and it was great to see that the HTTPS certificate that Firebase Hosting automatically generated for https://jeffy.info came from Let's Encrypt:

Part one covered some basic terminology an setup that's referenced throughout this post.

Part three will dive into a specific service worker implementation that can be used to provide an offline-first experience for a Jekyll-based site.

Folks who can't wait for part three are welcome to check out the https://jeffy.info service worker implementation ahead of time.

I also covered the material in this blog post in a presentation at the {static is} The New Dynamic Meetup:

Decisions, decisions

With those preliminary definitions out of the way, we can focus on the question at hand: how do you provide an offline-first experience for your templated site?

I'm going to outline three different approaches, each with their own benefits and drawbacks. Choosing the right approach requires balancing various tradeoffs, and the aim of this post is to walk through the plusses and minuses of each strategies, so that you can make an informed decision about what works best for your site.

Option 1: Cache entire HTML documents

How it works

This approach uses the Cache Storage API to keep a copy of the fully rendered HTML document that corresponds to each URL. The documents might be precached when the service worker is installed, or the caches might be populated via a runtime caching strategy that adds to the cache as users browse from page to page.

Benefits

Service worker simplicity

The service worker needed to implement this type of strategy is relatively straightforward. The fetch handler can check to see whether event.request.mode === 'navigate', and if so, use a stale-while-revalidate strategy to handle the request for the HTML document.

Minimal additional maintenance

While you need to create and deploy a service worker script, there isn't anything additional that you need to deploy and maintain. The same HTML documents that you've previously generated and deployed can continue to be served the same way.

Multiple layout template flexibility

Instead of a single layout template, some sites might find themselves using multiple layouts to generate the final HTML. For example, all documents served from the URL prefix /blog/ might use blog_layout.tmpl, while all documents served from under /news/ might use news_layout.tmpl.

Because the complete HTML documents are stored and retrieved from the cache, the service worker doesn't need any special knowledge about which underlying layout was used to generate the page.

That also means that a subset of URLs that aren't generated via templating at all—perhaps a site's about.html page, for instance—can be handled via the same logic used for all the other URLs.

Drawbacks

Cache overhead

Let's return to our diagram of the "smushening" process, which takes our template, combines it with each of our individual content files, and then results in a complete HTML document:

The blog_layout.tmpl file is used to generate each of the final HTML documents, and that means that the size of each HTML file is roughly equal to the size of the template file plus the size of the page-specific content.

If your template file is X bytes, and your have N output HTML files, you're incurring X * N bytes of duplicated cache contents, due to size of the templated portion of each final HTML document.

If X is a fairly small number (a template file of less than 1kb is common) and/or N is small (say, only a few dozen unique HTML files), then the amount of cache storage used is negligible. However, if you're using larger templates, or you know that you have hundreds or even thousands of HTML pages that a user might have cached, the overhead can start impacting those users who are storage constrained.

Messy updates

While the cache overhead isn't a showstopper, the compromises involved in updating previously cached content is more of a concern. Let's assume that we have foo.html, bar.html, and foo_bar.html HTML files stored in our cache.

If we were to make some updates to the foo.md content that's used to populate foo.html, our update strategy is to ensure that foo.html eventually gets refetched from the network. This might happen via a normal stale-while-revalidate flow, in which case the new content will only be available the second time a user revisits the page. Or it might happen by explicitly purging the existing foo.html entry from the cache ahead of time, making the new content available for the next visit.

But what if we make an update to blog_layout.tmpl? Maybe we've changed our navigation bar, or updated some header text. The impact of this change ripples beyond a single cache entry—all of our cached HTML files that depended on blog_layout.tmpl are now out of date.

We have the same options for dealing with this as before: let a stale-while-revalidate caching strategy gradually update the stale entries as users revisit pages, or proactively purge the out of date cache content, which in this case could mean invalidating our entire cache. There are serious downsides to each approach, though.

If we rely on a stale-while-revalidate runtime caching strategy to gradually update our cache, users will see inconsistencies across page navigations. The changes made to blog_layout.tmpl will only take effect after they revisit pages multiple times. If a user returns to a previously cached page months later, they'll still see your old layout, which can be jarring after they've gotten accustomed to seeing layout changes on fresh pages.

To avoid jarring your users, proactively purging all cached HTML that relies on a modified template is arguably the best approach. But now you're faced with another tradeoff: the performance and offline benefits of caching are diminished if users' caches are invalidated frequently. The effort that you put into implementing a caching strategy is wasted if you have to throw your entire cache away due to even small updates to your site's layout.

Real-world examples

A number of my colleagues, including Matt Gaunt, Paul Kinlan, and Sérgio Gomes, are using this option for their blogs.

Option 2: Use an Application Shell architecture

How it works

The Application Shell architecture is covered in great detail in this article by Addy Osmani and Matt Gaunt. My talk from the 2015 Chrome Dev Summit also covers similar ground, for those who prefer video:

While the Application Shell architecture is often talked about in reference to "web apps," it's definitely applicable to the types of templated "content sites" that we're talking about here.

The general approach is to repurpose your existing page structure, i.e. what's defined in your blog_layout.tmpl template, to serve as your Application Shell. This should be a valid, standalone HTML file (let's call it shell.html) that includes a placeholder element that the dynamic content gets inserted into at runtime, via client-side templating.

The dynamic content could be the same raw content sources—foo.md, bar.md, etc.—in which case the Application Shell's JavaScript would need to convert the content to HTML at runtime, prior to inserting it into the DOM. Or you might go through an additional step and convert the raw content into HTML snippets via a server-side process, in which case the content snippets can be inserted directly into the DOM at runtime.

You can use either a precaching or a runtime caching strategy like stale-while-revalidate to keep both shell.html and the underlying content up to date, while still serving them cache-first.

Benefits

Clean updates

Your structural HTML (shell.html) and your content are cached independently, so when you make changes to a page's content or to your site's layout elements, cache invalidation is simple and efficient. The only cache entries that need to be updated is either the content itself, or the entry for shell.html. If shell.html does get updated, then the updates will immediately apply to all pages on your site that share that Application Shell, ensuring that your site looks the same as the user moves from page to page. You eliminate the risk of a months-old cached page being shown, jarring a user with an inconsistent layout.

Low-overhead precaching

Using this architecture opens the door to precaching more of your site's content. Larger precache coverage means that pages a user hasn't previously navigated to will still work offline and load quickly. There are two reasons why aggressive precaching is more viable:

First, each piece of content can be cached as-is, independent of the App Shell's HTML. The cache overhead concerns with full-page caching don't apply, and as a developer, you don't have to worry about wasting as much bandwidth and space as you would if you were precaching full HTML documents.

Second, and more importantly, clean updates mean that you're much less likely to end up throwing away data once it's been precached. The only time you'd have to expire and redownload precached content is if that specific content is updated. A substantial precache payload is makes much less sense if you know that it will all end up expired each time you tweak your site's template.

Drawbacks

Routing logic in your service worker

In the Application Shell model, your service worker needs to have special logic in place to handle navigation requests. While the incoming request might be for a URL like https://example.com/2016/12/foo.html, your service worker needs to respond with your cached shell.html document, not with foo.html (which won't be cached in this model). Your Application Shell is then responsible for performing client-side templating and inserting the correct content into the DOM, based on whatever the request URL is.

This works fine when you only have one common layout, defined in shell.html, that's shared by all the pages on your site. But if there's a subset of pages on your site that use completely different layouts, like https://example.com/about.html, your service worker needs to know not to respond to those navigation requests with shell.html.

Your service worker is now an HTTP router, examining incoming navigations requests and serving the right type of response for each URL. If there's a simple URL pattern that can be used to match all of the requests that can be handled with the shell.html layout, then you're in good shape—something like the following might suffice:

self.addEventListener('fetch', (event) => {
	const yearMonthPrefix = new RegExp('/d{4}/d{2}/');
	if (event.request.mode === 'navigation') {
		if (event.request.url.matches(yearMonthPrefix)) {
			// Use the Application Shell to handle requests like
			// https://example.com/2016/12/foo.html
			event.respondWith(caches.match('shell.html'));
		} else {
			// Use an appropriate runtime caching strategy, like
			// stale-while-revalidate, to handle requests like
			// https://example.com/about.html.
		}
	} else {
		// Use an appropriate runtime caching strategy for
		// non-navigation requests, like requests for
		// images or other resources.
	}
});

But if you don't have that level of consistency in your URL structure, of if there's a subset of pages that fall under the /year/month/ prefix but use a completely different template, accurately reflecting that routing logic in your service worker gets much trickier and you need to construct a bespoke solution.

Duplicated effort

If you've already got a templated site, adopting the Application Shell architecture will usually mean duplicating pieces of your existing infrastructure. You need to take your blog_layout.tmpl and convert it into a shell.html file, adding to it the necessary client-side templating logic to populate your shell.

You might also need to add in a build step that takes original Markdown sources and converts them to HTML snippets, in in lieu of having to perform that Markdown conversion inside your Application Shell.

Finally, if your site relies on any sort of custom routing or templating rules that are implemented server-side, that routing logic needs to be moved into your service worker, as explained in the previous section.

This duplication means that there are more opportunities for pieces of your site to get out of sync. If you make changes to your blog_layout.tmpl, but the corresponding changes aren't made to shell.html, then browsers which lack service worker support will see one thing, while browsers that have a service worker responding with your Application Shell will see something else. Similar issues could arise if your routing rules need tweaking—they could potentially need to be changed in three places (server-side, client-side in SPA-style JavaScript, and client-side in service worker JavaScript) depending on how complicated your routing needs are. Trisomorphic routing: it's actually A Thing!

@adactioJournal Shows there are fantastic opportunities, though. I've yet to see someone nail "trisomorphic" routing (server + JS + SW).

— Nolan Lawson (@nolanlawson) May 25, 2016

Proper automation of your build process can ensure that the overhead and risk of duplicated pieces getting out of sync is minimal, but that's one more thing to keep track of.

Real-world examples

The iFixit PWA sample (the source of which is part of the sw-precache project) is an Application Shell populated with dynamic content from the iFixit API.

Option 3: Service worker templating

How it works

With this approach, you take the logic needed to smush together your templates and content and implement it within your service worker.

This doesn't mean that you'd do away with your site's existing build process, though. You can't assume that when a user visits your site there's going to be an active service worker, so you still need to serve complete HTML pages via your normal web server. But when a user returns to your site using a browser that supports service workers, they no longer have to request those complete HTML pages in order to display your site. They should already have your site's templates cached, and they may or may not have the page's content cached as well. So, at worst, only a very minimal amount of page-specific content needs to be requested, and at best, your service worker can assemble the complete HTML immediately, without having to go to the network at all.

Benefits

Clean updates and low-overhead precaching

Both the clean updates and low-overhead precaching benefits of the App Shell model apply here, as well.

No need to adopt Single Page App patterns

While the App Shell approach might seem familiar to developers who are familiar with writing client-side JavaScript and using the Single Page App (SPA) pattern, not every developer who manages a templated site with be comfortable with that model. You don't have to write and deploy a SPA when you use the service worker templating option, but you end up with most of the same benefits.

(Of course, there's a significant engineering effort required to properly implement service worker templating, but it's a different kind of effort…)

Drawbacks

A JavaScript-friendly templating system is a must

This approach is only viable if you're using a templating system that has a JavaScript implementation. And because the code will be run inside of a service worker, JavaScript code that requires features specific to the node environment, like filesystem support, won't work.

Fortunately, the JavaScript ecosystem is vibrant, and there's a decent chance that you'd find a JavaScript implementation of many templating systems. Running the JavaScript code through browserify can often smooth over the differences between the node and service worker runtime environments.

Heavyweight service worker code

In order to get your templating system working inside of your service worker, you'll almost certainly need to bundle in a number of external dependencies. Compared to a svelte service worker that implements a basic runtime caching strategy, you'll need to transfer more bytes of JavaScript each time your service worker is fetched from the network.

Your service worker is almost certainly going to spend more time executing code, since the "smushening" process that would otherwise be done at build-time is effectively run within a user's browser each time it display a page. The amount of overhead that this adds depends on how efficient your JavaScript templating system is and how powerful each of your users' devices are.

Routing logic in your service worker

This was covered in detail in the App Shell's drawbacks section; the same routing considerations apply here. The main difference is that instead of serving a cached shell.html file when the route matches, you need to kick off your templating logic when there's a matching navigation request.

Duplicated effort

This is also similar to the drawback with using an App Shell. Using this approach requires that you continue to run the "smushening" process like you were previously doing, but then additionally start serving not only the final HTML documents, but also the unprocessed template and content files, since those pieces will need to be fetched and cached by the service worker. You'll need to make sure that whenever a template or content is updated, both the final HTML as well as the raw files are updated on your server.

You'll also probably end up duplicating some of the work that your current build process does to generate metadata about your site. For example, Jekyll maintains it own list of recent posts and uses it to populate the index page for a site. Your service worker needs similar data in order to construct the same page, so writing your own code to generate the metadata in a format that your service worker could consume, and keeping that metadata in sync whenever you update your site, is now required.

Real-world examples

My personal blog, https://jeffy.info/, is currently using service worker templating. We'll dive into the specifics of how that's implemented in the next part of this series!

Part two covers different strategies for caching and serving templated sites.

Part three will dive into a specific service worker implementation that can be used to provide an offline-first experience for a Jekyll-based site.

Folks who can't wait for part three are welcome to check out the https://jeffy.info service worker implementation ahead of time.

What's offline-first?

Let's see if I can get away with just embedding a tweet:

…"Offline first" is a serving strategy. Get as far as you can with local data before going to the network.

(serve-)offline-(content-)first.

— Jake Archibald (@jaffathecake) October 18, 2016

That's offline-first.

What's a templated site?

What I'm calling a templated site is built using multiple templates, combined with the actual text, images and other resources that make up the site's content, spread across multiple pages. The site's URLs uniquely identify the content specific to a page. The templates provide a structural layout shared across the pages.

This is all a convoluted way of describing what's otherwise known as a "content site", but that's deliberate: I want to avoid all the baggage that comes along with the "content site" label, especially the implication of what it's not—a "web app". What I'm describing are considerations for a particular architectural equation: templates + content = your site. If you've got templates, and some source of content, and you mix them together (either ahead of time during a build process, or at runtime on a server), then you've got a templated site! If you want to also call it a web app, cool; if you want to call it a content site, or a blog, or a CMS-powered site, that's totally cool too.

Since it's always fun to draw contrasts, if I did have to hold up something in opposition to a templated site, it would be a single page application. There's a meaningful difference between the way SPAs handle navigations (using the History API to rewrite URLs, and swapping content out of an "application shell" container), and how templated sites handle navigations (as actual navigations, in which the current DOM is torn down, and built up again based on the new HTML). SPAs fill an important role in the web's ecosystem, and they are the right architecture to use for certain types of projects, but they're different beasts than templated sites.

In case it's not clear from that preamble, what you're reading now, assuming it's being read on https://jeffy.info/, is part of a templated site. Blogs, newspapers, and whole host of sites driven drive by a backend content management system are traditionally deployed as templated sites. If you're reading the syndicated copy of this on https://medium.com/, then I'm going to hazard a guess that the "templated site" label is also appropriate, but I'm not as familiar with how they implement things. ¯\_(ツ)_/¯

Anatomy of a templated site

All right: with what's hopefully a non-controversial set of a definitions out of the way, let's take a deeper dive into the different pieces that work together to produce a templated site. I'm going to focus on a specific framework, Jekyll, which I'm familiar with and that I use on https://jeffy.info/. The general concepts, if not the specific formats used for all the pieces, should apply broadly to other frameworks.

Templates!

Yes, templates. Templated sites have templates. Moving along…

Well, okay, there's more to explore here. Templates are usually small chunks of HTML that fill a certain structural role on a page—the header, the sidebar, the footer, etc. There's also likely to be a template that defines the HTML structure for the main bit of a page—the content—and which contains an insertion point where the words are plunked in from the content management system (more on that soon). These various templates are laid out in a… layout, which can be expressed as a template composed of those sub-templates.

Unfortunately, I lack the visual skills of some of my colleagues, but here's a rough sketch of what we're talking about, with the hypothetical smaller templates that work together to form a layout template for blog post:

The interesting bit here is that each of those smaller templates can be tweaked and modified individually, and sometimes (but not always) don't have to coordinate with each other or with the parent layout. You can imagine a rebranding in which a product name is changed in head.tmpl, or a copyright year is changed in foot.tmpl, without that requiring a larger change to any of the other templates or layouts.

Content!

Next up, let's assume that we have some content (like: this post) that we want to share with the world. That content might live in a database. It might live in individual files—Jekyll uses individual Markdown files. It might be accessed as JSON returned from a content management system's API. The important bits are the idea that there's a logical separation between the content for one page and the content for another, and the idea that content is independent from the overall page structure that's used to display it.

I don't know how to make diagrams of abstract content interesting, but... here's a depiction of content for you:

The process that smushes together the templates and the contents and outputs a final HTML document!

We've got some templates that are stitched together to make a layout, and we've got some content. What's left is smushing the layout and the content together to form a unique HTML document corresponding to each piece of source of content.

The specifics of the smushing vary greatly depending on what framework you're using. When you know that you have a potentially huge corpus of content (think: the entire archives of a newspaper), you might opt for a framework that smushes on demand, server-side, in response to a request from a client. When you're dealing with a slightly slimmer corpus (https://jeffy.info/: four posts and counting!), or if you want to avoid running custom code on a server, it can make sense to use a framework that smushes everything ahead of time. The you can serve the final HTML using any run of the mill HTTP server. That's what the Jekyll framework does.

Here's your requisite diagram:

The complete HTML documents are then displayed by the browser, blissfully unawares of all the behind-the-scenes architecture that was needed to get to this point.

If you'd like to turn the output of create-react-app into a progressive web app (PWA) with offline support, take a look at the create-react-pwa repo, and in particular, the GitHub diff of the minimal changes required.

create-react-app...

create-react-app solves a problem that many folks (including I) have run into: how can you get started with a straightforward, client-rendered, single page React app and build process, without spending hours researching a list of (sometimes conflicting) dependencies to list in your package.json? It's a project that came out of Facebook's React engineering a few months back, and has since gained some significant mindshare in the web developer community.

...and its limitations

In keeping with the fewer-depencies-are-better-dependencies philosophy behind create-react-app, the maintainers appear to be vigilant in the fight against scope creep, and are keeping the project lean. That's understandable, and it's left up to end users to decide what additional functionality to layer on top of the project's skeleton.

By design, the core of the build process isn't directly extensible. It's kicked off by npm run build and consists of

"scripts": {
  "build": "react-scripts build"
}

But! The opportunity's there to cleanly chain some additional commands after that initial react-scripts build, while keeping the react-scripts black box opaque, giving us the chance to modify the output of the original build process.

An Opportunity for PWA-ification

That gets to the heart of my investigation: what's the easiest way to guide developers starting from a fresh create-react-app towards the end goal of deploying a progressive web app? Specifically, what would it take to add in a service worker that provided performance benefits as well as a meaningful offline experience, as well as a web app manifest that contained application metadata?

Adding a Web App Manifest

This is just a standard JSON file with fields containing metadata useful for controlling the "add to homescreen" experience (currently only on Android devices). While each developer needs to choose their metadata wisely, there's nothing particularly challenging here from a technical perspective, and we just need to create the file and get it copied over to the build/ output directory as part of the npm run build process.

Adding a Service Worker

To handle the service worker, I (not surprisingly) turned to the sw-precache project. When added to a build process, it generates a service worker JavaScript file that will automatically version and keep all local static files—HTML, JavaScript, CSS, images, etc.—up to date. Because all of the create-react-app output is local static files (there's no server-side rendering or remote API calls by default, for example), sw-precache can handle everything we need with little configuration needed.

While I've traditionally used sw-precache as a JavaScript module inside of a gulp build process, it also sports a command-line interface, and it's simple to add in the sw-precache command to the end of the npm run build script chain.

The User Experience

Here's what the deployed PWA looks like on Chrome for Android, going through the steps of accepting the Add to Homescreen banner, and then launching it without a network connection.

Try it Yourself

The best way to visualize the changes to the build process, as well as the (small) modifications needed to the source code, is to view the GitHub diff between the starting point and the "final" PWA.

Take "final" with a grain of salt, because while you will end up with a build process that yields a progressive web app, there are many directions you might want to take the starter project, and some of those might entail a more complex service worker implementation. I've tried to cover some scenarios in the repo's README, including steps to take if you're using react-router and need arbitrary URLs to work offline, as well as how you can add in runtime caching strategies for calls to third party APIs and resources.

Beyond create-react-app

If you're looking for examples of PWAs build with React that go a bit beyond what create-react-app offers—for instance, that take advantage of server-side rendering or are built on third-party APIs—there are a few examples I could recommend:

• iFixit PWA (live deployment)
• Hacker News PWA (live deployment)

Blogging Software

I decided to go with Jekyll, which ships templates for blog posts, but makes it simple enough to put together standalone pages.

Web Hosting

GitHub Pages is free, which is nice, and (obviously) has first-class support for version control. GitHub Pages natively supports Jekyll, which means I just need to add the raw material to source control, and the _site content will be automatically generated. If you don't care about a custom domain then you can stop at this point—you can serve your site off of https://youraccount.github.io. No effort required for HTTPS support! jeffposnick.github.io is the GitHub repo with this site's content, if you want to check out what's going on under the hood.

Registering the Domain

I registered "jeffy.info" using Google Domains. Google Domains is in invite-only beta mode at the moment, but using an alternative domain registrar shouldn't change the process much. (I was surprised at how easy it was to get a .info domain—for whatever reason, they don't seem to be very popular. Check them out rather than settling for some obscure .com.)

Add a CNAME file to GitHub

As per the instructions, I added a CNAME file to the top-level of the repo and pushed to GitHub.

CloudFlare Setup

This was my first time using CloudFlare, so I needed to set up a (free) account. I told CloudFlare that I wanted it to take control over the "jeffy.info" domain, and I set up two A records for the bare ("apex") domain "jeffy.info" to resolve to the two published IP addresses for GitHub's servers. I also set up a CNAME record for "www" as an alias of "jeffposnick.github.io", so that "www.jeffy.info" will resolve.

Changing the Google Domains DNS Settings

In order for CloudFlare to start serving traffic for "jeffy.info", I needed to change the authoritative DNS settings for the domain to point to CloudFlare's severs. This was straight forward with the Google Domains UI (refer to your registrar's online help if you're using something else):

HTTPS-only Setup

CloudFlare auto-provisioned a certificate for "jeffy.info" withing a couple of minutes, which was awesome and as painless as promised. Make sure you use the "Flexible SSL" option, which is required to work with a GitHub Pages backend server. Using "Flexible SSL" means that the GitHub Pages ⇔ CloudFlare traffic isn't encrypted, but the CloudFlare ⇔ user's browser traffic is. That's sufficient for my goal of enabling web functionality that requires HTTPS to the end user's browser, but it's probably not a good idea if you're concerned about traffic vulnerabilities in the GitHub Pages ⇔ CloudFlare hop. I want to make sure that my blog is HTTPS-only, and CloudFlare's page rules interface allowed me to set that up:

Optimizing Content

Since CloudFlare is a full-fledged CDN, they offer a number of content optimization options. In general, I turned off most of the settings, but I did enable HTML + JS + CSS minification:

Since I'm relying on GitHub Pages to do my Jekyll's _site build, it seemed easiest to just let CloudFlare handle the minification rather than trying to work out a scripted solution.

CloudFlare offers image minification as well, but only as part of their paid offering. So I'm using gulp-imagemin locally on all my images, and pointing to the minified versions in posts. Be sure to minify your images!

Future Tweaks

I'm not particularly happy with the default Jekyll templates, and have already made a few changes. I'm sure there will be lots of twiddling with that to come. I'm also not particularly familiar with the best practices for a build workflow. I've got a basic gulpfile.js that I'm sure will grow over time.

I'm Jeff Posnick. I've been working on the Developer Relations team at Google NYC since 2007, first on the Ads APIs, then YouTube, and currently on the Open Web Platform.

About this Blog

I've been blogging elsewhere since 2003. The other 34 started out using Blosxom on a self-hosted web server. I moved it over to Blogger eventually.

I'm going to keep 34 around for personal topics. This blog, thirty-four, is going to focus on web technologies. Serving it via HTTPS, and having full control over the HTML/JavaScript/CSS, means that I'll be able to take advantage of some of the new features being added to the web platform, like those powered by service workers.

Stay tuned for a post detailing this blog's setup (spoiler alert: it's a Jekyll site hosted on GitHub pages, with the CloudFlare CDN providing HTTPS support.)