Speculation rules
Tags: thesession, performance, speed, frontend
Published: 2024-06-10 13:32:08

---
title: Speculation rules
published: true
date: 2024-05-21 08:59:24 UTC
tags: thesession,performance,speed,frontend
canonical_url: https://adactio.com/journal/21139
---

There’s a new addition to the latest version of Chrome called [speculation rules](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API). This already existed before with a different syntax, but the new version makes more sense to me.

Notice that I called this an addition, not a standard. This is _not_ a web standard, though it may become one in the future. Or it may not. It may wither on the vine and disappear (like [most things](https://killedbygoogle.com/) that come from Google).

The gist of it is that you give the browser one or more URLs that the user is likely to navigate to. The browser can then pre-fetch or even pre-render those links, making that navigation really snappy. It’s a replacement for the abandoned `link rel="prerender"`.

Because this is a unilateral feature, I’m not keen on shipping the code to all browsers. The old version of the API required a `script` element with a `type` value of “speculationrules”. That doesn’t do any harm to browsers that don’t support it—it’s a progressive enhancement. But unlike other progressive enhancements, this isn’t something that will just start working in those other browsers one day. I mean, it might. But until this API is an actual web standard, there’s no guarantee.

That’s why I was pleased to see that the new version of the API allows you to use an external JSON file with your list of rules.

I say “rules”, but they’re really more like guidelines. The browser will [make its own evaluation](https://developer.chrome.com/docs/web-platform/prerender-pages#chrome-limits) based on bandwidth, battery life, and other factors. This feature is more like `srcset` than `source`: you give the browser some options, but ultimately you can’t force it to do anything.

I’ve implemented this over on [The Session](https://thesession.org/). There’s a JSON file called `speculationrules.js` with the simplest of suggestions:

```
{
  "prerender": [{
    "where": {
        "href_matches": "/*"
    },
    "eagerness": "moderate"
  }]
}

```

The `eagerness` value of “moderate” says that any link can be pre-rendered if the user hovers over it for 200 milliseconds (the nuclear option would be to use a value of “immediate”).

I still need to point to that JSON file from my HTML. Usually this would be done with something like a `link` element, but for this particular API, I can send a response header instead:

```
Speculation-Rules: “/speculationrules.json"

```

I like that. The response header is being sent to every browser, regardless of whether they support speculation rules or not, but at least it’s just a few bytes. Those other browsers will ignore the header—they won’t download the JSON file.

Here’s the PHP I added to send that header:

```
header('Speculation-Rules: "/speculationrules.json"');

```

There’s one extra thing I had to do. The JSON file needs to be served with mime-type of “application/speculationrules+json”. Here’s how I set that up in the `.conf` file for The Session on Apache:

```
<IfModule mod_headers.c>
  <FilesMatch "speculationrules.json">
    Header set Content-type application/speculationrules+json
   </FilesMatch>
</IfModule>

```

A bit of a faff, that.

You can see it in action on [The Session](https://thesession.org/). Open up Chrome or Edge (same same but different), fire up the dev tools and keep the network tab open while you navigate around the site. Notice how hovering over a link will trigger a new network request. Clicking on that link will get you that page lickety-split.

Mind you, in the case of The Session, the navigations were already really fast—performance is a feature—so it’s hard to guage how much of a practical difference it makes in this case, but it still seems like a no-brainer to me: taking a few minutes to add this to your site is worth doing.

Oh, there’s one more thing to be aware of when you’re implementing speculation rules. You have the option of excluding URLs from being pre-fetched or pre-rendered. You might need to do this if you’ve got links for adding items to shopping carts, or logging the user out. But my advice would instead be: stop using GET requests for those actions!

Most of the [examples given for unsafe speculative loading conditions](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API#unsafe_speculative_loading_conditions) are textbook cases of when _not_ to use links. Links are for navigating. They’re [indempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent). For everthing else, we’ve got forms.