Sam Thorogood on web.dev

Love your cache ❤️

2020-12-11T00:00:00Z

This post is a companion to the Love your cache video, part of the Extended Content at Chrome Dev Summit 2020. Be sure to check out the video:

When users load your site a second time, their browser will use resources inside its HTTP cache to help make that load faster. But the standards for caching on the web date back to 1999, and they're defined pretty broadly—determining whether a file, like CSS or an image, might be fetched again from the network versus loaded from your cache is a bit of an inexact science.

In this post, I'll talk through a sensible, modern default for caching—one that actually does no caching at all. But that's just the default, and it's of course more nuanced than just "turning it off". Read on!

Goals #

When a site is loaded for the 2nd time, you have two goals:

Ensure that your users get the most up-to-date version available—if you've changed something, it should be reflected quickly
Do #1 while fetching as little from the network as possible

In the broadest sense, you only want to send the smallest change to your clients when they load your site again. And structuring your site to ensure the most efficient distribution of any change is challenging (more on that below, and in the video).

Having said that, you also have other knobs when you consider caching—perhaps you've decided to let a user's browser HTTP cache hold onto your site for a long time so that no network requests are required to serve it at all. Or you've constructed a service worker that will serve a site entirely offline before checking if it's up-to-date. This is an extreme option, which is valid—and used for many offline-first app-like web experiences—but the web doesn't need to be at a cache-only extreme, or even a completely network-only extreme.

Background #

As web developers, we're all accustomed to the idea of having a "stale cache". But we know, almost instinctively, the tools available to solve this: do a "hard refresh", or open an incognito window, or use some combination of your browser's developer tools to clear a site's data.

Regular users out there on the internet don't have that same luxury. So while we have some core goals of ensuring our users have a great time with their 2nd load, it's also really important to make sure they don't have a bad time or get stuck. (Check out the video if you'd like to hear me talk about how we nearly got the web.dev/live site stuck!)

For a bit of background, a really common reason for "stale cache" is actually the 1999-era default for caching. It relies on the Last-Modified header:

Assets generated at different times (in gray) will be cached for different times, so a 2nd load can get a combination of cached and fresh assets

Every file you load is kept for an additional 10% of its current lifetime, as your browser sees it. For example, if index.html was created a month ago, it'll be cached by your browser for about another three days.

This was a well-intentioned idea back in the day, but given the tightly integrated nature of today's websites this default behavior means it's possible to get into a state where a user has files designed for different releases of your website (e.g., the JS from Tuesday's release, and the CSS from Friday's release), all because those files were not updated at exactly the same time.

The well-lit path #

A modern default for caching is to actually do no caching at all, and use CDNs to bring your content close to your users. Every time a user loads your site, they'll go to the network to see whether it's up-to-date. This request will have low latency, as it'll be provided by a CDN geographically close to each end user.

You can configure your web host to respond to web requests with this header:

Cache-Control: max-age=0,must-revalidate,public

This basically says; the file is valid for no time at all, and you must validate it from the network before you can use it again (otherwise it's only "suggested").

This validation process is relatively cheap in terms of bytes transferred—if a large image file hasn't changed, your browser will receive a small 304 response—but it costs latency as a user must still go to the network to find out. And this is the primary downside of this approach. It can work really well for folks on fast connections in the 1st world, and where your CDN of choice has great coverage, but not for those folks who might be on slower mobile connections or using poor infrastructure.

Regardless, this is a modern approach that is the default on a popular CDN, Netlify, but can be configured on nearly any CDN. For Firebase Hosting, you can include this header in the hosting section of your firebase.json file:

"headers": [
  // Be sure to put this last, to not override other headers
  {
    "source": "**",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=0,must-revalidate,public"
    }
  }
]

So while I still suggest this as a sensible default, it's only that—the default! Read on to find out how to step in and upgrade the defaults.

Fingerprinted URLs #

By including a hash of the file's content in the name of assets, images, and so on served on your site, you can ensure that these files will always have unique content—this will result in files named sitecode.af12de.js for example. When your server responds to requests for these files, you can safely instruct your end-user's browsers to cache them for a long time by configuring them with this header:

Cache-Control: max-age=31536000,immutable

This value is a year, in seconds. And according to the spec, this is effectively equal to "forever".

Importantly, don't generate these hashes by hand—it's too much manual work! You can use tools like Webpack, Rollup and so on to help you out with this. Be sure to read more about them on Tooling Report.

Remember that it's not just JavaScript that can benefit from fingerprinted URLs; assets like icons, CSS and other immutable data files can also be named this way. (And be sure to watch the video above to learn a bit more about code splitting, which lets you ship less code whenever your site changes.)

Regardless of how your site approaches caching, these sorts of fingerprinted files are incredibly valuable to any site you might build. Most sites just aren't changing on every release.

Of course, we can't rename our 'friendly', user-facing pages this way: renaming your index.html file to index.abcd12.html—that's infeasible, you can't tell users to go to a new URL every time they load your site! These 'friendly' URLs can't be renamed and cached in this way, which leads me on to a possible middle ground.

The middle ground #

There's obviously room for a middle ground when it comes to caching. I've presented two extreme options; cache never, or cache forever. And there will be a number of files which you might like to cache for a time, such as the "friendly" URLs I mentioned above.

If you do want to cache these "friendly" URLs and their HTML, it's worth considering what dependencies they include, how they may be cached, and how caching their URLs for a time might affect you. Let's look at a HTML page which includes an image like this:

<img src="/images/foo.jpeg" loading="lazy" />

If you update or change your site by deleting or changing this lazy-loaded image, users who view a cached version of your HTML might get an incorrect or missing image—because they've still cached the original /images/foo.jpeg when they revisit your site.

If you're careful, this might not affect you. But broadly it's important to remember that your site—when cached by your end users—no longer just exists on your servers. Rather, it may exist in pieces inside the caches of your end user's browsers.

In general, most guides out there on caching will talk about this kind of setting—do you want to cache for an hour, several hours, and so on. To set this kind of cache up, use a header like this (which caches for 3600 seconds, or one hour):

Cache-Control: max-age=3600,immutable,public

One last point. If you're creating timely content which typically might only be accessed by users once—like news articles!—my opinion is that these should never be cached, and you should use our sensible default above. I think we often overestimate the value of caching over a user's desire to always see the latest and greatest content, such as a critical update on a news story or current event.

Non-HTML options #

Aside from HTML, some other options for files that live in the middle ground include:

In general, look for assets that don't affect others
- For example: avoid CSS, as it causes changes in how your HTML is rendered
Large images that are used as part of timely articles
- Your users probably aren't going to visit any single article more than a handful of times, so don't cache photos or hero images forever and waste storage
An asset which represents something that itself has lifetime
- JSON data about the weather might only be published every hour, so you can cache the previous result for an hour—it won't change in your window
- Builds of an open-source project might be rate-limited, so cache a build status image until it's possible that the status might change

Summary #

When users load your site a second time, you've already had a vote of confidence—they want to come back and get more of what you're offering. At this point, it's not always just about bringing that load time down, and you have a bunch of options available to you to ensure that your browser does only the work it needs to deliver both a fast and an up-to-date experience.

Caching is not a new concept on the web, but perhaps it needs a sensible default—consider using one and strongly opting-in to better caching strategies when you need them. Thanks for reading!

web.dev engineering blog #1: How we build the site and use Web Components

2020-04-09T00:00:00Z

This is the first post in web.dev's engineering blog. Over the coming months, we hope to share actionable insights from our work—so watch for posts with the Engineering Blog tag! Here we'll be covering the build process for our static site and the (optional!) JavaScript behind our web components.

web.dev provides content about building modern web experiences and allows you to measure your site's performance. Savvy users may have realized that our Measure page is just an interface for Lighthouse, which is also available in Chrome's DevTools. Signing in to web.dev lets you run regular Lighthouse audits on your site so you can see how its score changes over time. I'll be revisiting the Measure page a bit later, as we think it's fairly special. 🎊

Introduction #

Fundamentally, web.dev is a static site that is generated from a collection of Markdown files. We've chosen to use Eleventy because it's a polished, extensible tool which makes it easy to turn Markdown into HTML.

We also use modern JavaScript bundles that we only serve to browsers supporting type="module", which includes async and await. We also happily use features that are supported by evergreen browsers but not by a minority of older versions. Because we're a static site, JavaScript is just not required to read our content.

Once the build process—which involves generating static HTML and bundling our JavaScript with Rollup—is complete, web.dev can be hosted with a simple static server for testing. The site is almost completely static, but we have a few special needs that still benefit from a custom Node.js server. These include redirects for invalid domains, as well as code to parse a user's preferred language for an upcoming internationalization feature.

Static generation #

Each page on web.dev is written in Markdown. All pages include front matter, which describes metadata about each post. This metadata is ingested into the layout of each page, creating headings, tags, and so on. Here's an example:

---
layout: post
title: What is network reliability and how do you measure it?
authors:
  - jeffposnick
date: 2018-11-05
description: |
  The modern web is enjoyed by a wide swath of people…
---

The modern web is enjoyed by a wide swath of [people](https://www.youtube.com/watch?v=dQw4w9WgXcQ), using a range of different devices and types of network connections.

Your creations can reach users all across the world...

This front matter lets us define arbitrary properties like author(s), publish date, and tags. Eleventy conveniently exposes the front matter as data in nearly every plugin, template, or other context where we'd like to do something intelligent. The data object also contains what Eleventy describes as the data cascade—a variety of data pulled from each individual page, from the layout the page uses, and from data found in the hierarchical folder structure.

Each unique layout describes a different type of content and can inherit from other layouts. On web.dev, we use this feature to correctly frame different types of content (like posts and codelabs) while still sharing one top-level HTML layout.

Collections #

Eleventy provides a programmatic way to build arbitrary collections of content. This has let us build pagination support and generate virtual pages (pages that don't have a matching Markdown file on disk) for post authors. For example, we construct our authors pages using a template containing an expression for its permalink (so the template is re-rendered for every author) and a backing collection.

This results in, for example, a simple page containing all of Addy's posts!

Limitations #

Right now we can't easily hook into Eleventy's build process because it's declarative, rather than imperative: you describe what you want, rather than how you want it. It's difficult to run Eleventy as part of a larger build tool, as it can only be invoked via its command-line interface.

Templating #

web.dev uses the Nunjucks templating system originally developed by Mozilla. Nunjucks has the typical templating features like loops and conditionals but also lets us define shortcodes that generate further HTML or invoke other logic.

Like most teams building static content sites, we started small and added shortcodes over time—about 20 so far. Most of these just generate further HTML (including our custom web components). Here's an example:

{% Aside %}
[See how Asides work in the web.dev codebase](/handbook/web-dev-components/#asides)
{% endAside %}

It will end up looking like this:

But it's actually creating HTML that looks like this:

<div class="aside color-state-info-text">
<p><a href="/handbook/web-dev-components/#asides">See how Asides work in the web.dev codebase</a></p>
</div>

While out of the scope of this post, web.dev also uses shortcodes as a type of metaprogramming language. Shortcodes accept arguments, with one of their arguments being the contained content. It's not required that shortcodes return anything, so they can be used to build up state or trigger some other behavior. 🤔💭

Scripting #

As mentioned before, because web.dev is a static site, it can be served and used without JavaScript and by older browsers that don't support type="module" or our other modern code. This is an incredibly important part of our approach for making web.dev accessible to everyone.

However, our code for modern browsers consists of two major parts:

Bootstrap code, which includes code for global state, Analytics, and SPA routing
Code and CSS for Web Components which progressively enhance the site

The bootstrap code is fairly straightforward: web.dev can load new pages as a single-page application (SPA), so we install a global listener that listens for clicks on local <a href="..."> elements. The SPA model helps us maintain global state about the user's current session, as otherwise every new page load would trigger calls to Firebase to access a user's signed-in state.

We also specify a couple of different entrypoints into our site based on which URL you've hit, and load the correct one using dynamic import(). This cuts down on the number of bytes our users need before the site is enhanced with code.

Web Components #

Web Components are custom elements which encapsulate runtime functionality provided in JavaScript, and are identified by custom names like <web-codelab>. The design lends itself well to largely static sites like web.dev: your browser manages an element's lifecycle as a site's HTML is updated, correctly informing any elements when they are attached or detached from the page. And antiquated browsers just ignore Web Components altogether and render whatever is left in the DOM.

Each Web Component is a class with methods including connectedCallback(), disconnectedCallback(), and attributeChangedCallback(). web.dev's custom elements mostly inherit from LitElement, which provides a simple base for complex components.

While web.dev uses Web Components on many pages, nowhere is it more necessary than on the Measure page. Two elements provide the bulk of the functionality you see on this page:

<web-url-chooser-container></web-url-chooser-container>
<web-lighthouse-scores-container></web-lighthouse-scores-container>

These elements create further elements which provide more functionality. Importantly, these elements are just part of our regular Markdown source code—and our content team can add extended functionality to any page, not just the Measure node.

Our Web Components most commonly utilize the Container Component model, made popular by React, although this model is now a bit passé. Each -container element connects to our global state (provided by unistore), and then renders a visual element, which in turn goes on to render actual DOM nodes that have styling or other built-in functionality.

Global state and a Web Component

Our most complex Web Components exist to visualize global actions and state. For example, web.dev lets you audit your favourite site and then navigate away from the Measure page. If you return, you'll see that the task is still ongoing.

Our simple components purely enhance otherwise static content or create amazing visualizations (for example, each line graph is its own <web-sparkline-chart>), which has no relationship to the global state.

Let's chat #

The web.dev engineering team (Rob, Ewa, Michael, and Sam) will be following up with more technical deep dives soon.

We hope hearing about how we do things gave you some ideas for your own projects. Hit us up on Twitter if you've got questions or topic requests for this blog!