Speculation Rules API: Boosting Web Performance with Prefetching and Prerendering

The Speculation Rules API is designed to make websites faster by preparing for future navigations.

What Does “Future Navigation” Mean?

“Future navigation” refers to the pages the user might visit next. For example:

• On a blog’s homepage, the user might click on a post.
• On an e-commerce site, the user might go to the product details page or checkout.

The browser doesn’t know for sure where the user will go next, but based on the current page, it can make a good guess.

How Does It “Prepare” for These Navigations?

The Speculation Rules API allows the browser to “prepare” by preloading certain pages before the user actually clicks. It does this in two main ways:

• Prefetching: It downloads the HTML for the next possible page, but it doesn’t load all the images, CSS, or run JavaScript. This way, when the user clicks that link, the browser already has the main page file ready, so it can load faster.

• Prerendering: It goes a step further by fully loading the entire page in the background—including all images, CSS, and JavaScript. When the user navigates to that page, it feels instant because the browser doesn’t have to load anything new—it just switches to the prerendered page.

If you’ve ever used <link rel="prefetch"> or <link rel="prerender">, you’re probably familiar with how helpful it can be to preload resources before users need them. Well, this API is an upgrade to that.

Why Speculation Rules API?

The old methods—like <link rel="prefetch">—have been around for a while, but they’re limited. The Speculation Rules API builds on this and gives you more control and flexibility. Also, it avoids some of the problems with the now-deprecated <link rel="prerender">, like being Chrome-only and having issues with caching.

Here’s the key difference:

• Prefetching: Downloads the HTML of a future page but doesn’t fetch resources like images or scripts.
• Prerendering: Fully loads a future page in the background, including JavaScript execution, subresources, and layout.

Both of these actions can be specified using the Speculation Rules API, either through a <script> tag in your HTML or via HTTP headers. I’ll walk you through both options.

Using a <script> Tag

Let’s say you want to prerender most of your pages but exclude the login or checkout pages, which might have sensitive actions.

1
<script type="speculationrules">
2
  {
3
    "prerender": [
4
      {
5
        "where": {
6
          "and": [
7
            { "href_matches": "/*" },
8
            { "not": { "href_matches": "/logout" } },
9
            { "not": { "href_matches": "/*\\?*(^|&)add-to-cart=*" } }
10
          ]
11
        }
12
      }
13
    ],
14
    "prefetch": [
15
      {
16
        "urls": ["about.html", "contact.html"],
17
        "referrer_policy": "no-referrer"
18
      }
19
    ]
20
  }
21
</script>

This does two things:

• Prerender most pages, but not the /logout or /add-to-cart pages, which might cause unintended side effects.
• Prefetch the about.html and contact.html pages without sending referrer data, improving privacy.

The beauty of the API is that you can define exactly what you want to prefetch or prerender. That way, you avoid loading pages users are unlikely to visit or triggering sensitive actions prematurely.

Using HTTP Headers for Rules

One of the great things about the Speculation Rules API is that you don’t have to clutter your HTML with <script> tags if you don’t want to. Instead, you can define speculation rules using HTTP headers, which keeps your HTML cleaner and centralizes the rules in a more maintainable way.

Using HTTP headers also makes sense if you’re running a dynamic site and want to adjust rules on the server side without touching the front-end code. This can be a good strategy for larger websites or content-heavy sites, where maintaining speculation rules across multiple pages could get tricky.

How to Set It Up:

You can use the Speculation-Rules HTTP header to point to a JSON file that contains your prefetch and prerender rules. Here’s a simple example:

1
Speculation-Rules: "/rules/prefetch.json"

This tells the browser to load the speculation rules from the /rules/prefetch.json file.

What Should the JSON Look Like?

The JSON file you reference via the Speculation-Rules header should contain the same kinds of rules you’d use in the <script type="speculationrules"> tag, just structured externally. Here’s an example of a JSON file that uses both prefetch and prerender rules:

1
{
2
  "prerender": [
3
    {
4
      "where": {
5
        "and": [
6
          { "href_matches": "/checkout" },
7
          { "not": { "href_matches": "/logout" } }
8
        ]
9
      }
10
    }
11
  ],
12
  "prefetch": [
13
    {
14
      "urls": ["/about", "/contact"],
15
      "requires": ["anonymous-client-ip-when-cross-origin"],
16
      "referrer_policy": "no-referrer"
17
    }
18
  ]
19
}

• We’re prerendering the /checkout page but avoiding the /logout page.
• We’re prefetching the /about and /contact pages while making sure no referrer data is sent (using the no-referrer policy).

The requires field is used to ensure that cross-origin prefetches (from a different domain) only happen if they can be done without exposing the user’s identity (i.e., anonymous prefetches).

Serving the JSON with the Right MIME Type

One important thing to remember: when serving your JSON file, it must be served with the correct MIME type—application/speculationrules+json

If this isn’t set, the browser won’t recognize the file as a valid set of speculation rules. Here’s how you might set this up on a Node.js server using Express.

1
app.get('/rules/prefetch.json', (req, res) => {
2
  res.setHeader('Content-Type', 'application/speculationrules+json');
3
  res.sendFile('path/to/prefetch.json');
4
});

In this case, the server is serving the JSON with the correct MIME type so the browser knows to parse it as speculation rules.

When to Use Prefetching and Prerendering?

Here’s the trade-off: Prefetching is cheaper (less data, fewer resources used), but prerendering is faster (because everything is already loaded when the user clicks. However, prerendering uses more memory and bandwidth.

Prefetching:

• Great for pages that users might visit soon but aren’t guaranteed to.
• It only downloads the HTML of the page and keeps it in memory.
• If the user never navigates there, no harm done—resources aren’t wasted.

Prerendering:

• Ideal for pages users are highly likely to visit next (like the next step in a checkout flow).
• It loads everything—JavaScript, images, and subresources.
• This can be more resource-heavy, so you should only prerender when you’re pretty sure the user is heading there.

Real-World Example: Blog Navigation

Let’s say you’re running a blog. A good strategy could be to prefetch all the blog posts listed on the homepage but prerender the post the user is most likely to click next based on their browsing behavior.

1
<script type="speculationrules">
2
  {
3
    "prefetch": [
4
      {
5
        "urls": ["/post1", "/post2", "/post3"]
6
      }
7
    ],
8
    "prerender": [
9
      {
10
        "urls": ["/post1"]
11
      }
12
    ]
13
  }
14
</script>

With this setup, the posts will load faster when users navigate between them. You could even use JavaScript to dynamically adjust which post gets prerendered based on the user’s behavior, maximizing performance without wasting resources.

Why Is This Faster?

Without prefetching or prerendering, when you click a link, the browser has to:

1. Fetch the new HTML page from the server.
2. Parse the HTML.
3. Load all the resources (images, CSS, JavaScript).
4. Run the JavaScript and render the page.

With prefetching or prerendering, the browser has already done some or all of these steps before you click. It’s like packing your suitcase the night before a trip—it saves time because you’ve already done the work before you need it.

Why Not Do This All the Time?

While prefetching and prerendering can make websites feel faster, they also use up resources (network, memory, and CPU). If the browser downloads pages that the user never visits, it’s wasted effort. This is why the Speculation Rules API is smart—it gives you control over when and what to prefetch or prerender based on the user’s behavior.

Browser Compatibility and Performance

The Speculation Rules API is supported in Chrome 108+ and Edge 108+, with other browsers still working on adding support. Always check browser compatibility before shipping it to production.

The performance improvements, especially with prerendering, are significant. Pages load instantly—there’s no flicker or waiting for resources. When you set this up correctly, your site feels incredibly responsive, providing a seamless user experience.

However, prerendering consumes more memory and bandwidth, so be mindful about which pages you choose to prerender. Avoid loading unnecessary pages or triggering sensitive actions. Prefetching is generally a safer and more lightweight option to implement broadly, while prerendering can be used in high-confidence scenarios, such as the next step in a checkout flow.

The Speculation Rules API is still experimental, so always double-check browser support before using it in production. If you’re working on multi-page applications (MPAs), this could be the next big leap for performance optimization. However, it’s not suitable for single-page applications (SPAs), as it focuses on preloading entire documents rather than individual resources like JavaScript or CSS.

Experiment with both prefetching and prerendering to see which works best for your site, and always monitor resource usage to ensure that you’re not wasting bandwidth or causing unnecessary load on the user’s device.