# Speculation Rules API: Instant Prerender and Prefetch in Chrome

> How I use the Speculation Rules API to prefetch and prerender pages in Chromium — the JSON syntax, eagerness levels, document rules, and how it differs from Next.js Link prefetch.

URL: https://www.matthewswong.com/en/blog/speculation-rules-api-prerendering/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Published: 2026-08-01
- Updated: 2026-08-01
- Category: Web Dev

> **Key takeaway:** The Speculation Rules API lets you add a script type speculationrules JSON block that tells Chromium browsers which URLs to prefetch or prerender before a click. Prefetch downloads the response body; prerender fully renders the page in a hidden tab for near-instant navigation. Eagerness settings control how aggressively speculation fires.

The gap between a click and a painted page is where users feel a site as slow. I can shave milliseconds off the server, but the biggest single win is often to do the work before the click happens at all. The Speculation Rules API is the browser-native way to do exactly that: you declare which pages a visitor is likely to visit next, and Chromium fetches or even fully renders them in the background.

It replaces the older, more limited resource hints like link rel prefetch with a JSON grammar that can match links by URL pattern, choose between a cheap prefetch and a full prerender, and tune how eagerly the browser acts. In this post I walk through the syntax, the trade-off between prefetch and prerender, the eagerness levels, how it compares to the Next.js Link component, and the pitfalls I have hit in production.

## What the Speculation Rules API is

You opt in by dropping a script tag with the type speculationrules into the page. Its body is a JSON object with two possible keys, prefetch and prerender, each holding an array of rules. The simplest form is a list rule: you name the exact URLs you want the browser to speculate on. Feature detection is one line — HTMLScriptElement.supports with the argument speculationrules returns true where the API exists.

## Prefetch versus prerender: two very different costs

A prefetch downloads only the response body of the target page and holds it in an in-memory cache. It does not fetch subresources, and it does not execute the page's JavaScript. The cost is low, and the payoff on navigation is that the HTML is already there — you skip the network round trip but still parse, render, and run scripts after the click.

A prerender goes much further: the browser loads the page into a hidden tab, fetches every subresource, and runs its JavaScript, so activation on click is close to instant. The cost is correspondingly high — roughly that of opening the page in an invisible iframe. Prerender is same-origin by default; cross-origin same-site prerendering needs an explicit opt-in header from the target.

> Reach for prefetch as your safe default and promote a link to prerender only when you are confident it will be clicked — a checkout button, a paginated next page, the top search result. Prerender buys the most speed but spends the most bandwidth, memory, and CPU, so it should be earned, not sprinkled everywhere.

## Document rules and href matching

Hardcoding URL lists does not scale for a content-heavy site. Document rules solve this: instead of urls, you provide a where clause that matches links already on the page. href_matches takes a URL Pattern, and selector_matches takes a CSS selector, and you combine them with and and not. The rule below prerenders every same-origin link except the logout route and anything a class explicitly marks as unsafe.

## Eagerness: from conservative to immediate

The eagerness field decides when the browser acts on a rule. There are four values, and the default differs by rule type — list rules default to immediate, document rules default to conservative:

- immediate — speculate as soon as the rules are parsed, subject only to browser resource limits. This is the default for list rules where you have already committed to specific URLs.
- eager — act on the slightest hint, such as the cursor moving toward a link or a brief hover. Good for prefetching many likely destinations early.
- moderate — the balance point: fire when there is a reasonable signal, roughly a 200-millisecond hover or focus. A sensible choice for document-rule prerendering.
- conservative — wait until the user is essentially committing, on pointerdown or mousedown. This is the default for document rules and the cheapest interaction-based option.

> Chrome caps speculation to protect the device: at immediate or eager eagerness it allows up to 50 prefetches and 10 prerenders, but only 2 of each for the interaction-based moderate and conservative levels. Over-speculating wastes the user's bandwidth, memory, and CPU — and every prerender that is never clicked is pure waste, so match eagerness to real click likelihood.

## How it differs from Next.js Link prefetch

If you build with Next.js, the Link component already prefetches — but it is a different mechanism, not the Speculation Rules API. Next.js prefetches the route's own payload, the RSC data and JavaScript needed for a client-side transition, when a Link enters the viewport in production. Speculation Rules is a browser feature that can prefetch or fully prerender a real document navigation. The two are complementary rather than interchangeable:

| Aspect | Next.js Link prefetch | Speculation Rules API |
| --- | --- | --- |
| Who runs it | The Next.js framework in your app | The Chromium browser itself |
| What is loaded | Route RSC payload and JS for a client transition | A full document: HTML for prefetch, or a rendered page for prerender |
| Trigger | Link enters the viewport, in production only | Eagerness rules — immediate, eager, moderate, or conservative |
| Navigation type | Client-side SPA transition within the app | Real browser navigation to a URL |
| Browser support | Any browser that runs your React app | Chromium only — Chrome and Edge, not Firefox or Safari |

## Pitfalls I watch for

Speculation is powerful, but a few failure modes bite in production if you are not careful:

- Wasted prerenders. A prerender that is never activated has already spent full page cost. Aggressive document rules over broad selectors can prerender dozens of pages a user never opens — prefer conservative or moderate eagerness and narrow href_matches patterns.
- Analytics double-counting. Because a prerendered page runs its JavaScript before it is visible, naive analytics fire a pageview during prerender and again on activation. Guard initialization behind document.prerendering and the prerenderingchange event so a view is counted only when the user actually sees the page.
- Unsafe side effects on load. Any URL that mutates state on GET — sign-out, add-to-cart, one-time tokens, usage counters, ad impressions — must be excluded with a not href_matches clause, or a prerender will trigger it before the user ever clicks.

The analytics guard is small. Google Analytics and the Google Publisher Tag already account for prerendering, but for anything custom you defer initialization until the page is genuinely shown:

Browser support is the honest catch: the Speculation Rules API is Chromium-only. Chrome shipped prerendering via speculation rules in version 109 and the eagerness field in version 121, and Edge mirrors those releases. Firefox and Safari do not support it. That is fine — it is a progressive enhancement, so unsupported browsers simply navigate normally while Chromium users get the instant experience. Start with a conservative document rule on one high-intent link, watch your activation rate, and widen from there.

## Sources

- Prerender pages in Chrome for instant page navigations (Chrome for Developers)
- Speculation Rules API (MDN Web Docs)
- script type speculationrules reference (MDN Web Docs)
- Link component and prefetch (Next.js docs)

## Source links

- https://developer.chrome.com/docs/web-platform/prerender-pages
- https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API
- https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/speculationrules
- https://nextjs.org/docs/app/api-reference/components/link

## FAQ

### What is the Speculation Rules API?

It is a browser API that lets you declare, in a JSON script of type speculationrules, which URLs the browser should prefetch or prerender before the user clicks, so the next navigation feels instant. It supersedes older prerender resource hints with a flexible syntax based on explicit URL lists or document rules that match links on the page.

### What is the difference between prefetch and prerender?

Prefetch downloads the next document's response so navigation skips the network fetch, while prerender goes further and fully renders the page in the background so it appears instantly on click. Prerender is faster for the user but costs more CPU and memory and can trigger page side effects, so use it more conservatively than prefetch.

### What does the eagerness setting control?

Eagerness (conservative, moderate, eager, or immediate) tells the browser how aggressively to act on a rule. Conservative waits until pointer or touch down, moderate acts on hover, and eager or immediate act sooner. It lets you balance instant navigations against wasted prefetches, prerenders, and bandwidth.

### Which browsers support the Speculation Rules API?

It is supported in Chromium-based browsers such as Chrome and Edge. As of 2026 Safari and Firefox do not support it, so treat it as a progressive enhancement: browsers that do not understand the speculationrules script simply ignore it and your site keeps working normally.

### How is it different from Next.js Link prefetching?

Next.js Link prefetching fetches route data and JavaScript chunks for links in the viewport, within the framework. The Speculation Rules API is a browser-native mechanism that can prerender the entire next document, not just fetch its data. They can complement each other, but Speculation Rules works for any navigation and can fully prerender, which Link prefetch does not.

---

- HTML version: https://www.matthewswong.com/en/blog/speculation-rules-api-prerendering/
- Bahasa Indonesia: https://www.matthewswong.com/id/blog/speculation-rules-api-prerendering/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json