How to Use Speculation Rules for Instant Navigations

This guide is part of Speculative Loading & Prefetching, within Network & Server Response Optimization. The Speculation Rules API lets a page tell the browser which URLs to prefetch or prerender, and when. A prerendered page loads in an invisible tab with all its resources and scripts; when the user navigates to it, the browser activates it in milliseconds. For content sites, search pages and e-commerce listings, where the next click is often predictable, speculation rules can make a large share of navigations effectively instant.

Rules come in two forms: list rules with explicit URLs, and document rules that match links in the page by URL pattern or CSS selector. Each rule has an eagerness that determines the trigger: immediate, eager, moderate (hover around 200ms, or pointer down) and conservative (pointer or touch down). Getting good results is mostly about choosing patterns and eagerness, excluding unsafe URLs, and checking what actually happens in DevTools.

Rapid Diagnosis

• Open DevTools → Application → Speculative loads to see rules, candidates and status (not triggered, running, ready, failure with reason).
• Check document.prerendering in a prerendered page and activationStart in its navigation entry.
• Check navigation types in RUM to see how many navigations were prerendered.
• Check failure reasons: unsupported features, memory limits, cross-origin restrictions, or server errors.

Root Cause Analysis: Why Rules Underperform

1. Wrong eagerness. Too conservative gives little lead time; too eager wastes resources.

2. Patterns that miss real links. Rules do not match the URLs users click.

3. Prerender failures. Pages using features disallowed during prerender, or responses with errors.

4. Limits. Browsers cap concurrent prerenders and skip speculation under data saver or low memory.

Step-by-Step Resolution

1. Start with document rules at moderate eagerness

<script type="speculationrules">
{
  "prerender": [{
    "where": { "and": [
      { "href_matches": "/*" },
      { "not": { "href_matches": ["/logout", "/cart/*", "/*\\?*add-to-cart=*"] } },
      { "not": { "selector_matches": ".no-speculate, [download]" } }
    ]},
    "eagerness": "moderate"
  }]
}
</script>
<!-- trade-off: matching all same-site links is simple and safe at moderate
     eagerness, but heavy pages still prerender on hover; exclude them explicitly. -->

2. Add list rules for high-confidence next pages

For the top search result or the next article in a series, an immediate list rule gives maximum lead time.

<script type="speculationrules">
{ "prerender": [{ "urls": ["/articles/part-2/"], "eagerness": "immediate" }] }
</script>

3. Deliver rules via header for many pages

The Speculation-Rules response header can point to an external JSON file (served with Content-Type: application/speculationrules+json), so rules can be updated centrally without changing templates.

4. Make pages prerender-safe

Delay analytics, ads and side effects until activation; avoid triggering permission prompts or media playback before activation.

function whenActivated(cb) {
  if (document.prerendering) document.addEventListener('prerenderingchange', cb, { once: true });
  else cb();
}
whenActivated(() => { sendPageView(); startChat(); });
// trade-off: deferring everything to activation delays work for prerendered pages
// slightly after display; keep rendering work in the prerender, defer side effects only.

Verification

In DevTools' Speculative loads panel, hover a matching link and watch the status move to "Running" then "Ready"; click and check that the navigation entry shows a non-zero activationStart. Use the panel's failure reasons to fix pages that cannot be prerendered. In RUM, track the share of navigations with type: prerender (web-vitals reports navigationType), their LCP, and hit rates.

Worked Example: A Documentation Platform

A documentation platform added a single moderate-eagerness prerender rule for all same-site documentation links, excluding API playground pages (which opened WebSocket connections) and downloads. Within a week, 44% of subsequent navigations were prerendered, LCP p75 for subsequent navigations dropped from 1.2 seconds to 0.3 seconds, and INP improved slightly because startup JavaScript had already run. Server requests increased by 11%; since documentation HTML was cached at the CDN with a 95% hit ratio, origin load was nearly unchanged.

Common Failure Reasons

DevTools lists specific reasons when a prerender is cancelled. Frequent ones include: the page used a feature not allowed in prerender before activation (some APIs are deferred, others cause cancellation); the response was not a 200 (redirects to other origins, errors); the user's device was low on memory; too many prerenders were in progress; the prerendered page was navigated cross-origin; or the user has a data saver setting. Many of these are expected and harmless. Persistent failures for a URL pattern indicate a page that needs fixing or excluding.

Rolling Out Rules Gradually

Start with conservative prefetch for all same-site links: it is cheap, safe and gives a baseline of how often speculation is used. Then add moderate prerender for one well-understood pattern — articles, documentation pages or product pages — and watch hit rates, failure reasons and server load for a week. Expand to further patterns one at a time. Because rules are just JSON, they can be served from a central file via the Speculation-Rules header and adjusted without redeploying templates, which makes tuning fast. Keep a list of excluded URL patterns with the reason for each exclusion, so future changes do not accidentally re-enable speculation on side-effecting URLs. Review the list whenever new routes are added.

Common Mistakes

• Prerendering logout, add-to-cart or one-time links. Side effects happen without a click.
• Firing analytics during prerender. Inflated page views.
• Immediate eagerness on broad patterns. Large waste and memory pressure.
• Assuming all browsers prerender. Non-Chromium browsers ignore rules.

Edge Cases

Single-page applications. Speculation rules apply to document navigations; SPA route changes use the framework's own prefetching.

Cookies and state. Prerendered pages see cookies at prerender time; state changes before activation may make content stale.

Cross-origin. Cross-origin prerender is limited; prefetch can work cross-site with restrictions.

Rules added dynamically. Rules inserted by script are honoured, useful for injecting predictions after load.

FAQ

Related

• Prerender vs prefetch cost trade-offs — choosing the right action.
• Avoiding analytics double counting on prerender — prerender-safe measurement.
• View Transitions API performance — animating instant navigations.