Speculation-Rules

The HTTP Speculation-Rules response header provides one or more URLs pointing to JSON resources containing speculation rules for prefetching and prerendering pages.

Table of Contents

Usage
- Prerendering restrictions
Directives
- value
Example
Takeaway
See also

Usage

The Speculation-Rules header tells the browser where to find JSON files defining speculation rules. The browser uses these rules to speculatively load pages a visitor is likely to navigate to next, reducing perceived load times. Prefetched pages have their resources fetched in advance, while prerendered pages are fully rendered in the background before navigation.

This header is an alternative to inline <script type="speculationrules"> elements and is useful when the HTML document is not directly editable, such as when a CDN or edge server injects the rules. The referenced JSON file must be served with the application/speculationrules+json MIME type. Cross-origin rule files require CORS headers (Access-Control-Allow-Origin).

When using relative URLs in the JSON file, include "relative_to": "document" so URLs resolve relative to the HTML document rather than the JSON file location.

Prerendering restrictions

Chrome enforces limits on speculative loads to prevent excessive resource consumption:

immediate and eager eagerness: up to 50 prefetch and 10 prerender speculations
moderate and conservative eagerness: 2 speculations per eagerness level, first-in-first-out

The browser disables speculative loading when Save-Data is enabled, Energy Saver mode is active on low battery, available memory is insufficient, or the user has disabled the "Preload pages" setting. Background tabs do not trigger speculations.

Several APIs are deferred until the prerendered page activates (becomes visible after navigation). Geolocation, notifications, permissions prompts, WebRTC, and fullscreen requests return pending promises during prerender and resolve after activation. Cross-origin iframes inside prerendered pages are not loaded until activation.

The document.prerendering property returns true while the page is in prerender state. The prerenderingchange event fires on activation, signaling the page is now visible. Analytics, ad impressions, and other side effects need to wait for this event.

document.addEventListener("prerenderingchange", () => {
  // page is now active, safe to track views
});

Prerenders are cancelled by removing speculation rule scripts from the DOM, returning Clear-Site-Data: "prerenderCache" from a server response, or calling window.close() from within the prerendered page.

Directives

value

The value is a Structured Fields List of Strings. Each string is a quoted URL pointing to a JSON file containing speculation rules. The JSON file defines prefetch and prerender arrays with rules controlling speculative loading behavior. The quotes around each URL are required.

Example

A CDN injects speculation rules via the response header. The browser fetches the JSON file and begins speculatively loading pages defined in the rules.

Speculation-Rules: "/cdn-cgi/speculation"

The JSON file at the referenced URL. The prefetch array lists URLs to fetch in advance. The prerender array lists pages to fully render in the background. The eagerness field controls when speculation triggers.

{
  "prerender": [{
    "source": "document",
    "where": { "href_matches": "/*" },
    "eagerness": "moderate"
  }],
  "prefetch": [{
    "source": "list",
    "urls": ["/products", "/about"]
  }]
}

An e-commerce platform references a storefront-specific rules file targeting product and category pages.

Speculation-Rules: "/assets/storefronts.specrules.json"

Rules hosted on an external CDN. Cross-origin rule files require Access-Control-Allow-Origin on the JSON response.

Speculation-Rules: "https://static.cdn.example.re/rules/prerender.json"

Pairing speculation rules with No-Vary-Search to reuse prefetched pages across URL query parameter variations. The expects_no_vary_search hint tells the browser to wait for an in-flight prefetch rather than starting a new request.

{
  "prefetch": [{
    "source": "list",
    "urls": ["/results?q=shoes"],
    "expects_no_vary_search":
      "params=(\"utm_source\" \"utm_medium\")"
  }]
}

Takeaway

The Speculation-Rules header points the browser to JSON files containing prefetch and prerender rules, enabling speculative loading without modifying the HTML document. Prerendered pages defer intrusive APIs until activation and are subject to browser-enforced limits on memory and concurrency.