Speculation Rules: prerender and prefetch for instant navigation

Optimizing a single page has a physical limit: network, server and device always need some time. There is, however, a way to make the next page appear instantly: prepare it before the user clicks. That is the idea behind Speculation Rules, an API in Chromium-based browsers that lets you declare which pages to fetch in advance (prefetch) or even render in advance (prerender) in the background.

Prefetch and prerender: the difference

The two modes have very different costs and benefits.

• Prefetch: the browser downloads only the HTML document of the destination page ahead of time. On click it saves the network time for the document, but it still has to download subresources, parse and paint.
• Prerender: the browser loads and renders the whole page in an invisible tab, running JavaScript too. On click the page is simply shown, often with no perceptible wait.

Prerendering gives the most impressive result, but it consumes bandwidth, memory and CPU, and if the user never visits the page that work is wasted. Prefetching is lighter and lends itself to broader use.

The syntax

Rules are written in JSON inside a script element with a dedicated type:

<script type="speculationrules">
{
  "prerender": [{
    "where": {
      "and": [
        { "href_matches": "/*" },
        { "not": { "href_matches": "/logout" } },
        { "not": { "selector_matches": ".no-prerender" } }
      ]
    },
    "eagerness": "moderate"
  }]
}
</script>

There are two ways to specify destinations:

1. list rules, with a urls array of exact addresses, useful when you already know the next page, for example the second step of a checkout flow;
2. document rules, with the where condition, which apply to links on the page that match criteria on the URL or on CSS selectors.

Rules can also be delivered by the server through the Speculation-Rules HTTP header, which points to a JSON file: handy when you do not want to touch template HTML.

Choosing how eager to be

The eagerness field decides when the browser should act:

For site-wide generic rules, moderate is a good starting point: the user's intent is reasonably clear and the time gained between hover and click is often enough. On touch devices, where hover does not exist, the behaviour adapts to different signals.

The browser also applies its own limits on the number of simultaneous speculations and may give up in unfavourable conditions, for example when data saver is on or memory is low.

Side effects to plan for

Prerendering runs the page as if it had been visited, and that has consequences.

Analytics and counters

If the analytics script records a page view on load, a page that was prerendered but never opened would be counted. The code must wait until the page actually becomes visible:

if (document.prerendering) {
  document.addEventListener('prerenderingchange', startAnalytics, { once: true });
} else {
  startAnalytics();
}

Many popular analytics tools already handle this case, but it is worth checking with your own.

Actions with server-side effects

Never speculate links that change something: logout, add-to-cart via URL, confirmations, deletions. Exclude them explicitly with not conditions, as in the example above. More generally, a GET request should never change state, and Speculation Rules are a good reason to fix the places where it does.

Server load

Every speculation is an extra request. The server recognizes it from the Sec-Purpose header, which contains prefetch and possibly prerender. You can use it to log these requests separately or, when overloaded, to reject them harmlessly: the browser will simply perform a normal navigation.

Compatibility and strategy

Speculation Rules are supported in Chromium-based browsers; others ignore the script element without errors. It is therefore a progressive enhancement: browsers with support gain speed, the others lose nothing.

A cautious strategy proceeds in stages:

1. start with prefetch and moderate on all internal links, excluding actions;
2. watch the volume of speculative requests in your logs and, in field data, the effect on LCP and TTFB of navigations;
3. move to prerender on the sections where the benefit is greatest, such as listings and product pages.

In Chrome DevTools, in the Application panel, the section dedicated to speculative loading shows the detected rules, the speculated pages and the outcome of each attempt.

In short

• Prefetch downloads the document in advance; prerender prepares the whole page.
• Rules are declared in JSON in the HTML or through the Speculation-Rules header.
• moderate is a good compromise for broad site-wide rules.
• Exclude actions with server-side effects and adapt analytics to document.prerendering.
• It is a progressive enhancement: browsers without support ignore it.