Modern prerender & The Speculation Rules API

Technical Deep Dive & Specifications

The Fall of Legacy <link rel="prerender">

In early HTML5, developers used:

<!-- ⚠️ DEPRECATED / LEGACY NO-OP IN MODERN BROWSERS -->
<link rel="prerender" href="/next-page.html">

Legacy prerendering had critical architectural flaws:

1. Uncontrolled Resource Spikes: It lacked fine-grained rules, crashing mobile devices by spawning heavy background processes.
2. Double Analytics Hits: Background prerenders counted as real page views on servers even if the user never clicked the link.
3. No Intent Detection: It executed unconditionally without knowing if the user hovered, touched, or scrolled near the link.

Consequently, modern browser engines deprecated legacy <link rel="prerender"> (downgrading it to a basic No-Store prefetch or ignoring it entirely) and designed the Speculation Rules API.

The Architecture of the Speculation Rules API

The modern Speculation Rules API is declared via an inline JSON script with type="speculationrules":

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "list",
      "urls": ["/checkout", "/account"]
    },
    {
      "source": "document",
      "where": {
        "and": [
          { "href_matches": "/articles/*" },
          { "not": { "selector_matches": ".no-prerender" } }
        ]
      },
      "eagerness": "moderate"
    }
  ]
}
</script>

+----------------------------------------------------------------------------------------------------+
|                               SPECULATION RULES JSON SCHEMA TAXONOMY                               |
+----------------------------------------------------------------------------------------------------+
| Field              | Allowed Values               | Technical Function                             |
|--------------------|------------------------------|------------------------------------------------|
| **Action**         | `"prerender"`, `"prefetch"`  | Whether to fully render page or only pre-cache.|
| **source**         | `"list"`, `"document"`       | Explicit array of URLs or CSS document rules.  |
| **urls**           | Array of URL strings         | Required when `source: "list"`.                |
| **where**          | Condition Object             | Filtering logic for `source: "document"`.      |
| `href_matches`     | Pattern string / Glob        | URL pattern (e.g. `"/blog/*"`, `"/product/*"`).|
| `selector_matches` | CSS Selector string          | DOM selector on `<a>` tags (e.g. `".quick"`).  |
| **eagerness**      | `immediate`, `eager`,        | Trigger threshold policy (see matrix below).   |
|                    | `moderate`, `conservative`   |                                                |
| **target_hint**    | `"_self"`, `"_blank"`        | Context target for activation.                 |
+----------------------------------------------------------------------------------------------------+

Eagerness Threshold Matrix

The eagerness property prevents wasted bandwidth by tying speculation triggers to real user intent:

The Prerender Lifecycle & Restricted APIs

When a document is prerendering in the background, the browser strictly isolates it to protect user privacy and avoid disruptive behavior:

[Hidden Prerender Pipeline]
1. HTML Streamed -> DOM Built -> CSSOM Parsed -> JavaScript Executed -> Render Tree Boxed.
2. SENSITIVE APIS RESTRICTED (Audio, Video Autoplay, Notifications, Geolocation, alert(), prompt()).
3. document.prerendering === true
                                |
                [User Clicks Link on Active Page]
                                |
                                v
[Instant Page Activation]
1. Hidden tab swapped into primary viewport (0ms Paint Time!).
2. 'prerenderingchange' Event fires on Document.
3. document.prerendering becomes false.
4. Paused analytics, audio streams, and interactive timers resume.

JavaScript Lifecycle Handling Code Pattern

// Check if the current page is being executed inside a hidden prerender tab
if (document.prerendering) {
  console.log('Page is prerendering in background... Delaying analytics beacon.');
  document.addEventListener('prerenderingchange', () => {
    console.log('Page ACTIVATED by user! Firing analytics beacon now.');
    sendAnalyticsPageView();
  }, { once: true });
} else {
  // Standard direct navigation
  sendAnalyticsPageView();
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 8–22: Declares speculation rules using <script type="speculationrules">.
  • "source": "document" tells the browser to monitor all <a> anchor links rendered in the DOM.
  • where.and specifies that any link matching /article/* that does not possess the .external class should be prerendered.
  • "eagerness": "moderate" instructs the browser to begin prerendering as soon as the user's cursor hovers over the article link for at least 200ms or on touchscreen pointer down.
• Lines 31 & 36: Internal article links that qualify for automatic background prerendering.
• Line 41: External link with class="external", automatically excluded from prerendering.
• Lines 49–62: JavaScript lifecycle monitor inspecting performance.getEntriesByType('navigation')[0].activationStart. If non-zero, the page was loaded from a pre-rendered background process with 0ms visual latency!

Expected Browser Render Output (DevTools Speculative Loads Tab)

Opening Chrome DevTools $\longrightarrow$ Application $\longrightarrow$ Speculative Loads:

+----------------------------------------------------------------------------------------------------+
| Speculative Loads Inspector                                                                        |
+----------------------------------------------------------------------------------------------------+
| URL                               | Action     | Eagerness | Status    | Discard Reason            |
|-----------------------------------|------------|-----------|-----------|---------------------------|
| /article/quantum-computing        | Prerender  | Moderate  | Ready     | - (Hovered for 200ms)     |
| /article/web-performance          | Prerender  | Moderate  | Ready     | - (Touchstart detected)   |
| https://external-news.com         | -          | -         | Filtered  | Excluded by selector rule |
+----------------------------------------------------------------------------------------------------+
* User clicks link -> Status changes to 'Activated' -> LCP = 0.00ms 🚀