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() }}:

To disable speculation rules injection:

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.

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.

circle-exclamation

Source Types

Document Source

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

List Source

Specify explicit URLs to prefetch or prerender:

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

circle-info

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:

Generated Output

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

Browser Support

Speculation Rules are supported in:

  • Chrome 109+ (prefetch)

  • Chrome 117+ (prerender)

  • Edge 109+

For unsupported browsers, the script tag is simply ignored.

circle-info

Check caniuse.com/speculation-rulesarrow-up-right for current browser support.

Best Practices

  1. Start conservative: Begin with conservative or moderate eagerness and monitor performance impact.

  2. Use prefetch for uncertain navigations: If navigation probability is below 80%, prefer prefetch over prerender.

  3. Prerender high-value pages: Use prerender for pages where instant navigation provides significant UX benefit (checkout, product details).

  4. Avoid prerendering heavy pages: Don't prerender pages with complex JavaScript, auto-playing media, or expensive API calls.

  5. Monitor resource usage: Speculation consumes bandwidth and memory. Use browser DevTools to monitor impact.

  6. Combine with analytics: Use navigation analytics to identify pages that benefit most from speculation.

Example: E-commerce Site

Last updated

Was this helpful?