No More Loading Times: How to Use the Speculation Rules API

The Speculation Rules API introduced this year offers extreme added value with minimal effort. A dream for every website operator. Find out more in the following article.

The Speculation Rules make it possible to predict browser activity and load entire pages in advance so that they can be displayed at lightning speed when required. This significantly improves loading speeds. This not only has a positive impact on the user experience, but also contributes significantly to improving Core Web Vitals, a key indicator of website performance.

We will teach you everything you need to know about the Speculation Rules API, from the basic concepts to how to use it to optimize the loading speed of your web presence. You'll learn why the use of this API has become essential in modern web development, how to get started with implementation and how to create Speculation Rules effectively. We will also give you insights into the settings for prerendering and prefetching and share examples and troubleshooting tips. The goal is to give you the tools to take full advantage of speculation to improve the performance and user experience of your website - even without a developer.

What is the Speculation Rules API?

The Speculation Rules API is a browser API developed by Google that enables rule-based assumptions to be made and supposed target pages to be loaded before they are called up. If the user then calls up such a page, it is displayed immediately and no longer needs to be loaded.

The Speculation Rules API introduces a more expressive and configurable syntax to specify which documents should be pre-fetched or pre-rendered. Using a structure defined in JSON format within a script type=“speculationrules”, developers can formulate rules for both prerendering and prefetching.

The speculation rules themselves can be placed in the HEAD or body area of the respective page. The rules themselves can be integrated either statically or dynamically.

Why should I use the Speculation Rules API?

Using the Speculation Rules API offers numerous benefits for websites and web applications to improve load time and user experience.

By proactively loading content based on user behavior, websites can take their responsiveness and user engagement to a new level. The integration of Speculation Rules ensures lightning-fast loading times. The integration effort is minimal and even users of a different browser can experience improvements.

Increased loading speed

Speculative loading is a crucial factor in improving website performance. It's like an intelligent assistant that anticipates your next move to load pages faster and cater to users with different internet speeds. This proactive approach optimizes user experience and page load times and makes content easily accessible on different devices. The special thing about this is that no complicated caching logic needs to be applied. The Speculation Rules are a pure browser feature and therefore a system-independent game changer!

Shorter loading times mean lower bounce rates and a longer time spent on the website. In addition, fast pages help to fulfill the Core Web Vitals. Of course, these are great benefits for search engines.

Improved user experience

The Speculation Rules can run in the so-called “eagerness” mode. This ensures that pages are dynamically preloaded that the user is likely to visit. If the user lingers on a link for just 300ms, this micro-interaction ensures that the page behind it is preloaded accordingly. The subsequent click on the link ensures that the page is displayed immediately. Users benefit from faster loading times and uninterrupted navigation, which leads to increased engagement.

This proactive approach not only increases user satisfaction, but also improves the key performance indicators of a website. Online stores in particular, which usually have many pages and invite users to browse, benefit enormously from this dynamic.

Fast and cost-effective implementation

Although the Speculation Rules API is still relatively new and unknown, there is already a large selection of best practice scripts for most major systems such as Magento 2, WordPress or Shopware. The implementation effort is extremely low in relation to the business value created and is therefore recommended to everyone. Before starting the implementation, you should take a look at your own site structure. URLs that contain or process relevant real-time data should not be preloaded. However, simple CMS or product pages should.

Unsupported browser and human cache warmer

It was mentioned at the beginning that the Speculation Rules API is a Chrome feature. This is currently still hidden behind an “experiment” flag and must be activated. Browser extensions such as uBlock Origin or similar ad blockers must also allow the preloading of pages.

Although these are already quite big hurdles and the question arises as to how much impact the use of Speculation Rules actually has, it also makes sense for at least one other reason. Especially for websites that are regularly updated or for stores that have many products, it makes sense to use the Speculation Rules API. This is because every user with activated Speculation Rules automatically ensures that unvisited pages also end up in the cache. A human cache warmer, so to speak.

First steps with the Speculation Rules API

To get started with the Speculation Rules API, you must first create a script type=“speculationrules” element and define the speculation rules in a JSON structure in it. The speculation rules can be added either in the head or body section.

Speculation rules can be included either statically or dynamically.

To inform the browser which URLs should be pre-rendered, you can add JSON statements to your pages:

{
 "prerender": [
   {
     "source": "list",
     "urls": ["next.html", "next2.html"]
   }
 ]
}

You insert the JSON instructions for prefetching in a similar way.

It is possible to add multiple speculation rules to a page. In this case, you would instruct the browser at one of the following levels.

Prerequisites

Before you can use the Speculation Rules API, make sure your browser supports it. You can check browser support with the following code:

if (HTMLScriptElement.supports && HTMLScriptElement.supports('speculationrules')) {
  console.log('Your browser supports the Speculation Rules API.');
}

Current browser support

The Speculation Rules API is currently supported by the following browsers:

Support in other browsers is expected in the future, as the Speculation Rules API is still under development and is gradually being implemented by browser manufacturers.

Creating Speculation Rules

To create speculation rules, start by creating a script type=“speculationrules” element and define the speculation rules in a JSON structure within it. The speculation rules can be added in either the head or body section of the mainframe.

It is important to note that speculation rules in subframes are not considered and speculation rules in pre-rendered pages are only considered when a user navigates to the page itself.

Speculation rules can be integrated either statically or dynamically. With dynamic setup, you should always refer to the support documentation for future developments and use cases that may become available in the future.

To inform the browser which URLs should be pre-rendered, you can include JSON statements on your pages:

{
 "prerender": [
   {
     "source": "list",
     "urls": ["next.html", "next2.html"]
   }
 ]
}

You insert the JSON instructions for prefetching in a similar way.

It is possible to add multiple speculation rules to a page. In this case, you would instruct the browser at one of the following levels.

Definition of rules

The Speculation Rules API allows developers to configure rules with a structure defined in JSON format within a script type=“speculationrules”, which the browser can use to decide which URLs to pre-render (Mozilla).

Here is an example of how the Speculation Rules API works by specifying a list of URLs to be prefetched or pre-rendered:

{
 "prerender": [
   {
     "source": "list",
     "urls": ["https://example.com/page1.html", "https://example.com/page2.html"]
   }
 ]
}

The same applies to prefetching, which can often be a good first step on the way to prerendering:

{
 "prefetch": [
   {
     "source": "list",
     "urls": ["https://example.com/script.js", "https://example.com/styles.css"] 
   }
 ]
}

Recently, Google announced new improvements to the Speculation Rules API, which now provides the ability to automatically find links using document rules. URLs are retrieved from the document based on a where condition:

{
 "prerender": [
   {
     "source": "document",
     "where": {
       "href_matches": ["https://example.com/*"],
       "href_excludes": ["https://example.com/login", "https://example.com/admin"]
     },
     "eagerness": "eager"
   }
 ]
}

In this code snippet, all URLs on the page are taken into account for prerendering, with the exception of those that lead to the login and admin pages. You also specify a level of eagerness - eager (immediately), moderate (on a hover of 200ms) and conservative (on mouseover or touchdown).

Alternatively, or in conjunction with href, CSS selectors can also be used to find links on the current page:

{
 "prefetch": [
   {
     "source": "document",
     "where": {
       "selectors": ["a[rel=prefetch]"]
     }
   }
 ]
}

If you're using the Speculation Rules API, you can check it with the speculative load background services in the Chrome app tab when you inspect the page.

Settings for prerendering and prefetching

The Speculation Rules API provides several settings for prerendering and prefetching that allow developers to customize speculative loading to your specific needs. These settings are based on urgency and user interaction and help to avoid overutilization of resources.

Immediate speculation (Immediate)

The “immediate” setting is not dependent on user actions and therefore has higher limits. It enables dynamic capacity adjustment by removing older speculations. With this setting, up to 50 prefetch and 10 prerender requests can be performed.

Eager speculation (Eager)

Similar to “immediate”, the “eager” setting is not dependent on user actions and offers higher limits. It also enables dynamic capacity adjustment by removing older speculations. With “eager”, up to 50 prefetch and 10 prerender requests can be executed.

Moderate Speculations

In contrast to “immediate” and “eager”, the “moderate” and “conservative” settings are user-controlled and follow a First-In-First-Out (FIFO) principle with an upper limit of 2. With these settings, the oldest speculations are replaced by new ones to save memory.

Conservative speculations

As with “moderate”, speculations are also user-controlled with the “conservative” setting and follow the FIFO principle with an upper limit of 2. Older speculations are replaced by new ones to conserve resources.

It is important to choose the right settings for speculative loading to achieve optimal performance while avoiding overuse of resources. Developers should analyze user interaction and behavior on their website to determine the most appropriate settings for prerendering and prefetching.

Examples for implementation

Here are some examples of how you can implement the Speculation Rules API in practice:

Sample code

To inform the browser which URLs should be pre-rendered, you can add JSON statements to your pages:

{
 "prerender": [
   {
     "source": "list",
     "urls": ["next.html", "next2.html"]
   }
 ]
}

Similarly, insert the following JSON instructions for prefetching.

It is possible to add multiple speculation rules to a page, in which case you would instruct the browser at one of the following levels.

Practical example Magento 2

In Magento 2, the Speculation Rules API can be introduced in a few simple steps and without an additional module. This guide shows you how to create the specified Speculation Rules in a Magento CMS block and integrate it into the head area of each page using a widget.

1. Create CMS Block

• a. Log in to the Magento Admin Panel.
• b. Go to Content > Blocks.
• c. Click on Add New Block.
• d. Fill in the details:
  • i.Block Title:Speculation Rules Script
  • ii.Identifier:speculation_rules_script
  • iii.Store View: Select the store views in which the block should be available.
  • iv. In the Block Content, insert the following code:

<script>
if (HTMLScriptElement.supports &&
    HTMLScriptElement.supports('speculationrules')) {
    const specScript = document.createElement('script');
    specScript.type = 'speculationrules';
    // Correctly declare specRules as a constant within the block scope
    const specRules = {
        "prerender": [{
            "source": "document",
            "where": {
                "and": [
                    {
                        "href_matches": "/*"
                    },
                    {"not": {"href_matches": "/*(customer|login|logout|auth|cart|checkout|search|download|redirect|rewrite|store|productalert)/*"}},
                    {"not": {"href_matches": "*.pdf"}},
                    {"not": {"selector_matches": ".do-not-prerender"}},
                    {"not": {"selector_matches": "[rel=nofollow]"}},
                    {"not": {"selector_matches": "[target=_blank]"}},
                    {"not": {"selector_matches": "[target=_parent]"}},
                    {"not": {"selector_matches": "[target=_top]"}}
                ]
            },
            "eagerness": "moderate"
        }]
    };
    specScript.textContent = JSON.stringify(specRules);
    document.body.append(specScript);
}
</script>

• v. Click on Save.

2. Create Widget

• a. Go to Content > Widgets.
• b. Click on Add Widget.
• c. Configure the following settings:
  • i.Widget Type: CMS Block
  • ii.Design Package/Design Theme: Select your current theme.
• d. Click on Next.

3. Configure Widget Options

• a.Widget Title: Speculation Rules Script Widget
• b.Under Widget Settings:
  • i.CMS Block: Select the Speculation Rules Script block.
• c.Under Layout Updates:
  • i. Click on Add Layout Update.
  • ii.Display on: All pages
  • iii.Container: Before Body End (or Head depending on theme customization).
• d. Click on Save and Clear Cache.

4. Clear Caches

• a. Go to System > Tools > Cache Management.
• b. Select all caches and click on Clear Cache.

The introduction of this tuned Magento 2 rules set takes immediate effect and shows direct influence on the Core Web Vitals. The results are clear in the screenshot below. The values for TTFB, LCP and FCP have all increased significantly!

Troubleshooting and tips

Here are some common errors and best practices when using the Speculation Rules API:

Common errors

1. Wrong heuristics for prerendering - If pages or resources are incorrectly preloaded when the user is unlikely to need them, this can consume unnecessary bandwidth and negatively impact the load time for pages that are actually visited.
2. Missing or incorrect eagerness values - The API allows you to define different degrees of prediction (e.g. eager or conservative). Too aggressive prerendering can waste resources, while too conservative configuration does not utilize the potential of the API.
3. Security and privacy issues - If a page contains confidential or user-specific content, it should not be preloaded without explicit user interaction. Otherwise, personal data could be unintentionally loaded into the cache.
4. Failure to consider network and device conditions - Preloading pages can lead to increased data consumption and delayed loading times on mobile devices or with slow connections. Adaptive strategies are necessary to avoid such problems.

Best Practices

The Speculation Rules API can optimize loading times in eCommerce and improve the conversion rate. To use it efficiently and safely, the following best practices should be observed:

1. Targeted prerendering based on user behavior - Use heatmaps or analytics data to predict the most likely click targets. For example, product detail pages from search results or popular categories are good candidates for prerendering.
2. Adaptive strategies for mobile users - On mobile devices or with slow connections, no aggressive prerendering should be done. Use eagerness: “conservative” and consider network conditions to conserve bandwidth.
3. Exclude checkout and login pages - Never prerender pages with personal data (e.g. checkout, customer account) as this poses privacy risks and can cause session problems.
4. Adapt rendering to promotions and campaigns - During marketing campaigns, specific landing pages, discount promotions or bestseller pages can be prioritized for rendering to optimize the shopping experience.
5. PerformA/B tests to measure performance - Test whether the API actually has a positive effect on loading times and conversion rates. Compare CTRs, bounce rates and load times between with and without Speculation Rules API before rolling it out globally. This is especially possible with tools like RumVision.

Webinar recommendation: Performance boost with Speculation Rules

If you want to learn more about the Speculation Rules API, Real User Monitoring (RUM) and Core Web Vitals, watch this webinar:
Performance Optimization with Real User Monitoring, Core Web Vitals & the Speculation Rules API
Here you will learn how RUM, Core Web Vitals and the Speculation Rules API can help to improve the performance of your website in the long term.

Conclusion

In this article, we have introduced the basic concepts and applications of the Speculation Rules API, a groundbreaking technology that has the potential to significantly increase website loading speeds. By implementing this API, developers can improve the user experience while boosting their website's search engine rankings. The flexibility and customizability of Speculation Rules offer an advantage in the field of web development and allow for a more proactive design of user interaction.

By utilizing the Speculation Rules API, new doors are opening into the future of seamless web performance where long load times are a thing of the past. Developers are encouraged to explore the strategies and best practices presented and implement them in their projects to take full advantage of speculative loading. The continued evolution and improvement of this technology promises exciting possibilities for the future of web development, ensuring that digital experiences become increasingly efficient and enjoyable for users worldwide.

About the author

David Lambauer is a respected expert in the field of e-commerce and founder of the agency run_as_root GmbH based in Würzburg. Since its foundation in 2021, the agency has established itself as an innovative partner for Magento 2, Hyvä and Shopware solutions. With an international team of specialists and a high standard of code quality, run_as_root sets standards in the development of modern and powerful online stores.

As an Adobe Certified Master Architect and long-standing Magento Association Contributor, David brings in-depth knowledge and extensive experience to every project. He is also the creator of the Mage-OS DevDocs and a sought-after speaker at international conferences.

With a strong focus on innovation, quality and transparency, David Lambauer stands for dynamic and future-oriented solutions that sustainably promote the success of his customers.

Published on 02/13/2025 | No More Loading Times: How to Use the Speculation Rules API| KS