Speculation Rules

The Speculation Rules API enables near-instant page loads by allowing developers to define rules for browsers to prefetch or prerender pages before a user clicks.

Speculation Rules are stable and enabled by default in Hyvä 1.4.0 and newer.

By default, Hyvä prefetches links on user hover.

Configuration

Configure speculation rules in Magento 2 Admin: Stores → Configuration → Hyvä Themes → General → Speculation Rules.

Method

Available options:

• prefetch (default)
• prerender
• Disabled (no speculative loading)

Eagerness

Configure speculation rule eagerness. Options:

• immediate
• eager
• moderate (default)
• conservative

Prerendering: Benefits and Considerations

While prerender offers instant navigation, be aware of its trade-offs.

Benefits

Prerendering renders a page in a background tab, downloading resources, executing JavaScript, and preparing it for display. When a user clicks, the page swaps to the foreground almost instantly, providing the fastest navigation.

Resource Consumption

Prerendering is more resource-intensive than prefetching, consuming more client memory/CPU and increasing server load by processing pages users might not visit. Use it for pages with a very high probability of being the next navigation.

Analytics

Prerendering can inflate analytics. Scripts (e.g., Google Analytics) may record a "page view" even if the user never sees the page, leading to inaccurate metrics.

Some analytics platforms handle prerendering automatically. For others, add custom logic to your tracking code to check for prerendering and fire page view events only upon page activation (when the user navigates to it).

Use the document.prerendering property and the prerenderingchange event to control code execution and manage analytics.

const initAnalytics = () => {
  console.log('Page is now visible. Firing analytics.');
  // Place your analytics initialization or page view tracking code here
  // For example: gtag('event', 'page_view', { ... });
};

if (document.prerendering) {
  // Page is being prerendered. Wait for it to be activated.
  document.addEventListener('prerenderingchange', initAnalytics);
} else {
  // Page was not prerendered, so initialize analytics right away.
  initAnalytics();
}

Excluding Paths

Prevent speculation for specific URL paths, such as customer/account/logout or cart actions, which should not be prefetched.

Exclude paths via Layout XML or your module's frontend/di.xml.

Layout XML

Add paths to the exclude list in your theme's layout XML by passing arguments to the speculationrules block.

<referenceBlock name="speculationrules">
    <arguments>
        <argument name="exclude_list" xsi:type="array">
            <item name="logout_path" xsi:type="string">customer/account/logout</item>
            <item name="add_to_cart_path" xsi:type="string">checkout/cart/add</item>
        </argument>
    </arguments>
</referenceBlock>

frontend/di.xml

Achieve the same result by adding paths to the excludeFromPreloading argument of the Hyva\Theme\ViewModel\SpeculationRules view model in your module's frontend/di.xml.

In this configuration, the excluded path is the item's name, with its value set to true.

This method also allows disabling default excluded paths; however, be aware of potential frontend behavior impacts.

<type name="Hyva\Theme\ViewModel\SpeculationRules">
    <arguments>
        <argument name="excludeFromPreloading" xsi:type="array">
            <item name="my/dynamic/url" xsi:type="boolean">true</item>
        </argument>
    </arguments>
</type>

Resources & Articles

• Caniuse Support: Caniuse Speculation Rules
• Mozilla Developer Docs: Speculation Rules API
• Chrome Developer Docs: Chrome Dev - Preload Pages