/
Speculation Rules

Speculation Rules

Overview:

The module has been introduced to enable and manage Speculation Rules.

Instalation:

This module is part of MageSuite metapackage

Optional installation when metapackage is not used

composer require "creativestyle/magesuite-speculation-rules" ^1.0.0


What are speculation rules?

”The Speculation Rules API is designed to improve performance for future navigations” - it is a modern feature that allows pages to be prefetched or prerendered before the user actually clicks a link.



Configuration:
Configuration is available in: Admin → Stores → Configuration → MageSuite → Speculation rules

image-20251218-100836.png
Speculation rules configuration - view in admin panel

 

When enabled a <script type="speculationrules"> tag is injected into the page <head>, the script content is created from the admin configuration.
The script: is added globally via default.xml, and is explicitly removed on checkout (checkout_index_index.xml).

Details:

  • Block: MageSuite\ThemeHelpers\Block\SpeculationRules

  • Layout injection: head.additional

  • Condition: ifconfig="speculation_rules/general/is_enabled"

Available options:
Is Enabled:

  • Yes / No


Speculation Rules JSON:

  • Textarea field

  • Must contain a valid JSON object (Validation: required, JSON syntax validation with custom validate-json validator available in admin area)

  • Visible only when “Is Enabled” is set to Yes

Default configuration:
By default, the module is disabled, but the following configuration is recommended and aligned with the MageSuite core structure:
{
"prefetch": [
{
"where": {
"and": [
{ "not": { "selector_matches": "a[href*='/customer/account']" }},
{ "not": { "selector_matches": "a[href*='/checkout']" }},
{ "or": [
{ "selector_matches": ".cs-image-teaser__link" },
{ "selector_matches": ".cs-product-tile__name-link" },
{ "selector_matches": ".cs-product-tile__thumbnail-link" },
{ "selector_matches": ".cs-product-tile__container" },
{ "selector_matches": ".cs-offcanvas-navigation__link" },
{ "selector_matches": ".cs-navigation__link" },
{ "selector_matches": ".cs-footer-links__item a" },
{ "selector_matches": ".cs-brand-carousel__slide-link" }
]}
]
},
"eagerness": "moderate"
}
]
}

 

What does this configuration do
This configuration defines a set of links that are eligible for speculation using the prefetch strategy. It does not immediately prefetch pages by itself. Instead, it provides the browser with hints about which navigations may be prefetched when certain user interactions or heuristics occur. The configuration applies to links originating from image teasers, product tiles, navigation elements, and footer links, while explicitly excluding customer account pages and checkout-related URLs.
Prefetching is triggered only when the browser decides it is appropriate, for example: on hover interactions on desktop devices, based on viewport and proximity heuristics on touch devices (for eagerness: "moderate")1.

How does it actually works && configuration possibilities
To learn more about the available Speculation Rules capabilities, please refer to the following resources:

How to implement in your project
If you decide to enable Speculation Rules (which I encourage to do), you have a safe starting point in the form of a default JSON configuration that should suit most projects.
However, it is important to review the elements, components, and areas that are critical for your website and adjust the configuration accordingly to ensure maximum benefit from Speculation Rules. After becoming familiar with the documentation, you can also experiment with different eagerness strategies and validate the results.