Speculation Rules API

Static site generators like Hugo are already incredibly fast. By serving pre-compiled HTML directly from a CDN, Time to First Byte (TTFB) is often measured in milliseconds. But what if navigating between pages could feel completely instantaneous? What if the next page was already fully rendered before the user even clicked the link?

Enter the Speculation Rules API. It’s a modern browser feature that allows developers to write JSON instructions telling the browser exactly which URLs to prefetch or prerender based on precise eagerness thresholds. Today, we are going to explore how to integrate a highly configurable Speculation Rules implementation natively into Hugo.

Prefetching vs. Prerendering

Before diving into the configuration, it’s crucial to understand the two core mechanisms of speculation:

• Prefetch: The browser downloads the raw HTML payload of the target URL in the background. When the user navigates, the browser processes the HTML, downloads required assets (CSS/JS), and paints the page. It’s light on bandwidth and memory.
• Prerender: The browser opens a hidden tab, downloads the HTML, executes the JavaScript, paints the CSS, and holds the fully rendered page in memory. When the user navigates, it instantly swaps the hidden tab into view. This feels like a Single Page Application (SPA) transition but requires more memory and CPU.

Understanding Eagerness

The Speculation Rules API uses “eagerness” to decide when to trigger the preload action. This Hugo implementation exposes these thresholds directly via configuration variables.

Breaking Down the Configuration

This Hugo setup uses a custom [params.speculation] block in the hugo.toml file. Let’s explore how these variables dictate browser behavior dynamically.

1. Header Links (Site Menus)

The main navigation (menus) is the most heavily trafficked area of any site. Configuration allows you to explicitly preload these.

[params.speculation]
    headerLinks = "prefetch"
    headerEagerness = "eager"

2. Article Targeting

When a user lands on the homepage or is reading an article, they are highly likely to read your newest content next.

    articles = "prefetch"
    articleFolder = "posts"
    articleCount = 3
    articleEagerness = "eager"
    articleCAEagerness = "moderate"

3. Pinned Articles

For high-priority, evergreen content pinned to the top of your lists. You can target these specifically without consuming your standard article limits.

    pinnedArticle = "prerender"
    pinnedArticleEagerness = "immediate"

4. Taxonomy Tuning

Category and Tag pages behave similarly to article lists, but require their own scoping.

    taxonomies = "prerender"
    taxonomyCount = 3
    taxonomyEagerness = "eager"
    taxonomyCAEagerness = "moderate"

5. In-Article Contextual Routing (Same Origin)

When a user is deeply engaged reading a specific post, their clicking behavior is highly predictable.

    sameOriginEagerness = "eager"

6. Safe Cross-Origin Prefetching

Preloading links that point away from your site is risky. You don’t want to accidentally prerender a heavy external site in the background, consuming user bandwidth.

    crossOrigin = true
    crossOriginEagerness = "moderate"

Limitations & Browser Fallbacks

Speculation rules are treated strictly as speculative hints and progressive enhancements. The browser reserves the right to ignore your rules, and in certain conditions, prerendering or prefetching will fail completely:

1. User Settings Disabled: Browsers like Chrome and Edge allow users to toggle off speculative loading under their privacy/performance settings (e.g., “Preload pages for faster browsing and searching”). If disabled, speculative loads will silently halt.
2. Ad Blockers & Extensions (uBlock Origin): Browser extensions designed for privacy or network filtering—most notably uBlock Origin, frequently block network pre-fetching to prevent unrequested background connections. When uBlock Origin is enabled with its “Disable pre-fetching” setting turned on, background speculation requests will fail.
3. Data/Battery Saver Mode: If a user’s mobile device or laptop is running on Data Saver or Low Power Mode, Chromium browsers automatically suppress speculative background tasks to protect client resources.

Browser Compatibility

The Speculation Rules API is a modern web standard currently championed heavily by Chromium-based browsers.

• Supported: Google Chrome, Microsoft Edge, Opera, and Brave (version 109 and newer) fully support JSON-based speculation rules.
• Not Yet Supported: Safari (WebKit) and Mozilla Firefox do not yet natively support the <script type="speculationrules"> tag.