We all love quick and snappy online shopping experiences. Fast navigations from one product page to the next reduce friction and allow people to find all the products they want in that store.
To achieve that, one could implement a smart mechanism that predicts where the user is likely to go and preloads those pages earlier. Solutions like that do already exist, but have historically required custom JavaScript to work. The Speculation Rules API aims to provide a native way of achieving the same effect.
After experimenting with the API for over a year, we finally released our platform-wide configuration back in June 2025.
Read on to learn what this feature is all about and how it made Shopify stores up to 180ms faster across all loading metrics in supported scenarios.
The Speculation Rules API Jump to heading
The Speculation Rules API is essentially configuration developers send to the browser. That configuration takes form as a JSON that tells the browser:
- The speculative loading techniques it should use -
prefetchorprerender. - Which links it should target - specific lists, URL patterns, or even CSS selectors.
- How aggressive it should be - through the
eagernesssetting.
There are a lot of different scenarios that can be configured. You can learn more about them in the MDN documentation.
It is all about trade-offs Jump to heading
It may be tempting to make the browser immediately prerender all of the links on the page. However, there are two important trade-offs that you need to consider when preparing the configuration.
The first one has to do with eagerness. The more aggressive it is, the bigger the risk of loading the page that a visitor won’t ever visit in the current session. This wastes their data and may slow down the loading of the current URL. There can also be cases where the cached content becomes stale if you fetch it early.
The second one is related to the preloading strategy. While prerender is very powerful, it also executes all scripts (including analytics). This can lead to overreporting in terms of page views and other related events. prefetch on the other hand is very safe, but only the initial HTML response gets cached, limiting the performance improvements.
Speculative loading for Liquid storefronts Jump to heading
Our main goal was to come up with a Speculation Rules API configuration that we can enable for the entire platform. This proved to be a proper challenge that required many iterations. There are multiple routes that you definitely don’t want to speculate upon like a logout link. We also encountered a few browser bugs that had to be fixed and released before moving further.
Nonetheless, I’m happy to report that all of the Liquid-based storefronts have been benefiting from the speculative loads since late June.
In terms of the implementation, we settled on sending the configuration via the Speculation-Rules header in the main HTML response:
At the time of writing this article, our rules are configured to prefetch all of the key safe routes with a conservative eagerness. This means the browser will prefetch the link right when the user presses down the mouse button or places their finger on the screen. All of that without waiting for the release action that is required to trigger the actual navigation.
It’s worth noting that stores can still define their own rules via the <script type="speculationrules"> element. The browser treats each configuration separately so you won’t lose the benefit of the default one we provide.
Impact on storefronts Jump to heading
Below are the charts showcasing their impact on the three main loading metrics across all percentiles:
The difference between speculative (Treatment) and normal (Control) navigations across Time To First Byte, First Contentful Paint, and Largest Contentful Paint.
As you can see, there's a measurable improvement. Here are the key remarks:
- The numbers are based on the A/B test data collected from real visitors.
- Both “Control” and “Treatment” groups only include same-site navigations using a fairly modern Chromium-based browser.
- We’re seeing an average 130ms improvement on desktop and 180ms on mobile across all percentiles, and across all loading metrics.
We are very happy with the results, which have been consistent over the period where we experimented with the feature. The difference between mobile and desktop is particularly interesting. I previously mentioned that conservative eagerness triggers on mousedown or touchdown events. This suggests that on average tapping takes around 50ms longer than clicking.
Unfortunately, the way we set up the A/B test didn’t allow us to draw any conclusive business impact numbers. We learned our lessons and will definitely make sure it is possible with any subsequent work.
Moving forward Jump to heading
Speculation Rules provided a significant platform-wide win for the users doing same-site navigations. This is why we’re motivated to make them even more impactful.
One of the key ingredients to achieve that is Safari support. Our team is already working on such a contribution to Webkit, but it’s too early to announce anything concrete yet. If we succeed, this will be a significant milestone, given how much mobile traffic is coming from iOS.
More aggressive rules are on our radar as well. Our biggest challenge here is making sure visitors never see any stale content. We’ve already shipped one of the changes that should tackle some of those issues. All of the cart mutating endpoints (e.g. /cart/update, /cart/add, etc.) now return the Clear-Site-Data: "prefetchCache", "prerenderCache" header. It tells the browser to purge the relevant caches when the cart contents change.
On top of all of that, The Chrome team is not sitting idle either. They are currently experimenting with eagerness adjustments, which promise better intent heuristics on mobile. We’re also discussing the possibility of adding a new speculation that would be a middle ground between the existing ones. It would be similar to prerender, but without running any scripts until the actual navigation (reducing analytics issues and API call overhead).
Exciting future ahead Jump to heading
As you can see, there are many exciting things happening around making the Shopify platform even faster. We’ll definitely keep working on our Speculation Rules API implementation as the technology evolves.
You may decide to experiment with the feature yourself. Just remember to be very cautious to avoid the potential stale content and tracking issues explained in the talk.