Speculation Rules

Speculation Rules is a browser API that allows you to hint which pages the user is likely to navigate to next. The browser can then prefetch or prerender those pages in advance, making navigation feel instant.

Benefits

Instant navigation: Prerendered pages load instantly when clicked
Improved perceived performance: Users experience near-zero navigation time
Smart prefetching: Only fetch resources, not execute, for lighter optimization
Flexible rules: Target specific links by URL patterns or CSS selectors

Configuration

/config/packages/pwa.yaml

pwa:
  speculation_rules:
    enabled: true
    prefetch:
      - source: document
        eagerness: moderate
        href_matches: '/products/*'
    prerender:
      - source: document
        eagerness: conservative
        selector_matches: '.prerender-link'

Usage

Speculation rules are automatically injected when using {{ pwa() }}:

<!DOCTYPE html>
<html>
<head>
    {{ pwa() }}
    {# Speculation rules script is automatically included #}
</head>
</html>

To disable speculation rules injection:

{{ pwa(injectSpeculationRules: false) }}

Rule Types

Prefetch

Prefetch downloads resources in advance but doesn't execute them. This is lighter than prerendering and suitable for pages the user might navigate to.

pwa:
  speculation_rules:
    enabled: true
    prefetch:
      - source: document
        href_matches: '/blog/*'
        eagerness: moderate

Prerender

Prerender fully loads and renders the page in a hidden tab. When the user navigates, the page appears instantly. Use this for high-confidence navigation predictions.

pwa:
  speculation_rules:
    enabled: true
    prerender:
      - source: document
        selector_matches: 'a.primary-cta'
        eagerness: moderate

Prerendering consumes more resources than prefetching. Use it sparingly for pages with high navigation probability.

Source Types

Document Source

Match links in the current document using CSS selectors or URL patterns:

pwa:
  speculation_rules:
    prefetch:
      # Match by URL pattern
      - source: document
        href_matches: '/products/*'

      # Match by CSS selector
      - source: document
        selector_matches: 'a.prefetch-link'

      # Combine both (AND condition)
      - source: document
        href_matches: '/checkout/*'
        selector_matches: '.checkout-link'

List Source

Specify explicit URLs to prefetch or prerender:

pwa:
  speculation_rules:
    prefetch:
      - source: list
        urls:
          - '/popular-page'
          - '/frequently-visited'

Eagerness Levels

The eagerness property controls when speculation happens:

Level

Description

immediate

Speculate as soon as the rules are observed

eager

Speculate on any slight indication of navigation

moderate

Speculate on hover (200ms) or pointer down

conservative

Speculate only on pointer/touch down

pwa:
  speculation_rules:
    prerender:
      # High confidence - prerender immediately
      - source: document
        selector_matches: '.hero-cta'
        eagerness: immediate

      # Medium confidence - wait for hover
      - source: document
        href_matches: '/products/*'
        eagerness: moderate

      # Low confidence - wait for click intent
      - source: document
        href_matches: '/external/*'
        eagerness: conservative

Start with moderate or conservative eagerness and increase based on analytics data showing actual navigation patterns.

Advanced Options

Referrer Policy

Control the referrer sent with speculative requests:

pwa:
  speculation_rules:
    prefetch:
      - source: document
        href_matches: '/external/*'
        referrer_policy: 'no-referrer'

Generated Output

The bundle generates a <script type="speculationrules"> tag:

<script type="speculationrules">
{
  "prefetch": [
    {
      "source": "document",
      "where": {"href_matches": "/products/*"},
      "eagerness": "moderate"
    }
  ],
  "prerender": [
    {
      "source": "document",
      "where": {"selector_matches": ".prerender-link"},
      "eagerness": "conservative"
    }
  ]
}
</script>

Browser Support

Speculation Rules are supported in:

Chrome 109+ (prefetch)
Chrome 117+ (prerender)
Edge 109+

For unsupported browsers, the script tag is simply ignored.

Check caniuse.com/speculation-rules for current browser support.

Best Practices

Start conservative: Begin with conservative or moderate eagerness and monitor performance impact.
Use prefetch for uncertain navigations: If navigation probability is below 80%, prefer prefetch over prerender.
Prerender high-value pages: Use prerender for pages where instant navigation provides significant UX benefit (checkout, product details).
Avoid prerendering heavy pages: Don't prerender pages with complex JavaScript, auto-playing media, or expensive API calls.
Monitor resource usage: Speculation consumes bandwidth and memory. Use browser DevTools to monitor impact.
Combine with analytics: Use navigation analytics to identify pages that benefit most from speculation.

Example: E-commerce Site

/config/packages/pwa.yaml

pwa:
  speculation_rules:
    enabled: true
    prefetch:
      # Prefetch product pages on hover
      - source: document
        href_matches: '/products/*'
        eagerness: moderate

      # Prefetch category pages
      - source: document
        selector_matches: '.category-link'
        eagerness: moderate

    prerender:
      # Prerender checkout - high value page
      - source: document
        selector_matches: '.checkout-button'
        eagerness: conservative

      # Prerender "Add to Cart" result page
      - source: document
        href_matches: '/cart'
        selector_matches: '.add-to-cart'
        eagerness: conservative

PreviousEarly Hints

NextNon-Standard Parameters

Last updated 7 months ago

Was this helpful?