Speculation rules are a JSON block in a script tag that tells the browser which links it may load ahead of time. With prerender, the browser builds the next page in the background when a visitor shows intent to click, so the navigation appears instant. Browsers that do not support it ignore the block.
Most of the work we do on speed is about making a page load faster. Speculation rules attack the problem from the other side: load the page before the visitor asks for it, so that when they click there is nothing left to wait for.
This site ships one rule, on every page, in a single line of the build script. In a supporting browser, pages here usually open with no visible load. Adding it was the easy part. Deciding whether it was safe to add took more thought, and that is the part worth writing down.
What are speculation rules?
Speculation rules are instructions, written as JSON inside a script tag with the type speculationrules, that tell the browser which links on the page it is allowed to fetch or render before the visitor clicks them. They replace older hints such as link rel="prerender" with something more precise and controllable.
A rule has three parts: an action, a way of choosing links, and an eagerness setting that says how strong a signal the browser should wait for. There are two actions.
| Prefetch | Prerender | |
|---|---|---|
| What the browser does | Downloads the HTML of the next page | Loads the page fully in a hidden tab, including CSS, scripts, and images |
| Does page JavaScript run early | No | Yes |
| What the click feels like | Faster, the document is already in hand | Instant, the page is swapped in |
| Cost of a wrong guess | One wasted document request | A whole wasted page load |
What rule does this site use?
This site uses a single document rule that allows the browser to prerender any link to a page on this site except those under the API path, at moderate eagerness. Moderate means the browser waits for a sign of intent, such as the pointer resting on a link, before it starts building the page.
Here is the block from the page template in our build script. In the source it is one line. It is formatted here for reading:
<script type="speculationrules">
{
"prerender": [{
"where": { "and": [
{ "href_matches": "/*" },
{ "not": { "href_matches": "/api/*" } }
]},
"eagerness": "moderate"
}]
}
</script>The where clause is what makes this a document rule: instead of listing URLs, it describes them, and the browser applies the description to every link it finds on the page. That suits a generated site, because new pages are covered without touching the rule.
The exclusion deserves a plain explanation. Nothing on this site links to /api/ today. The only thing that lives there is the contact form endpoint, which is reached by a POST request and not by a link. The exclusion is a guard so that a link added later can never be loaded speculatively by accident.
How eager should the browser be?
Eagerness controls how early the browser acts on a rule. Higher eagerness means more navigations feel instant and more speculative loads are wasted. For rules that match many links, a middle setting that waits for hover or the start of a press is usually the right balance between speed and waste.
From most to least aggressive, the settings are:
immediate: speculate as soon as the rule is seen.eager: speculate on a very slight hint of intent.moderate: speculate when the pointer rests on a link briefly, or when a press begins.conservative: speculate only once a press or tap has started.
We chose moderate because our rule matches every link on the page. With immediate, a page with thirty links would try to prerender far more than anyone will visit. On touch screens there is no hover, so the browser relies on other signals, and those heuristics have changed between browser releases. Do not assume phones get exactly the desktop behaviour.
What does prerendering cost?
Prerendering costs a full page load for every guess, paid by the visitor's connection and by your server, whether or not the visitor ever opens the page. It also runs the page's JavaScript early, so anything a page does on load happens for pages nobody saw.
That second cost is the one that catches people. Before you turn this on, go through what your pages do when they load:
- Analytics and ad scripts can record a view for a page that was never shown, unless they are written to wait for activation.
- Links that change something, such as a sign-out link or an add-to-cart URL reached by a plain GET request, must be excluded from the rule.
- Pages built per request on a server or from a database turn each hover into real compute.
- Heavy pages spend the visitor's data and battery on a guess.
This site is close to the best case. Every page is a static file, there are no analytics or advertising scripts to miscount, and no link changes any state. The same is true of the sites we deliver as static builds, such as Gayer Law, with 305 static pages, and One Stop Bail Bonds, with 271. A static page costs almost nothing to serve twice. That is one more argument in the static site or WordPress decision.
For a web application with accounts, the answer is more cautious: use prefetch, or use prerender with a narrow rule that names the few public pages worth it.
Which browsers support speculation rules?
Speculation rules are supported in Chromium-based browsers, which includes Chrome and Edge. Other browsers skip a script type they do not recognise, so the block is harmless there and those visitors get ordinary navigation. Treat it as an enhancement for part of your audience, not a fix for a slow site.
Even in a supporting browser, the rule is a permission and not a command. The browser limits how many pages it will prerender at once and can decline altogether, for example when the device is saving data or is short on memory. You cannot rely on any given navigation being prerendered.
So the baseline still matters. A page that is fast without help is fast for everyone, and we cover that in what makes a website fast. Speculation rules then remove the last visible delay for the visitors whose browser takes the hint.
How do you tell whether a page was prerendered?
A page can tell it is being prerendered by reading document.prerendering, which is true until the visitor actually arrives, and by listening for the prerenderingchange event that fires on arrival. Code that should only run for a real view, such as an analytics call, can wait for that event.
The timing APIs also account for it. A navigation timing entry carries an activationStart value, the moment the prerendered page was shown. We will be straight about a gap in our own code here: the telemetry line in our footer does not subtract that value, so on a prerendered page its paint time is measured from when the background load began, not from the click.
Prerendering also pairs well with cross-document view transitions. The morph between pages can begin immediately because the next page is already built.
Frequently asked questions
Do speculation rules improve SEO?
Not directly. They do not change what a search engine crawler sees. They can improve the loading experience real visitors have on later pages of a visit, in browsers that support them. Treat any ranking effect as unproven and add them for the visitor's sake.
Is this the same as link rel="prefetch"?
No. The older link hints are separate features with their own behaviour, and the old rel="prerender" hint no longer does a full prerender in Chrome. Speculation rules are the current mechanism, and they add document rules and eagerness settings the link hints never had.
Can speculation rules be added to a WordPress site?
Yes, a script block can be printed in the page head like any other tag, and recent WordPress versions include speculative loading in core. Be careful with plugins that count views or run code on page load, and exclude any URL that changes state when requested.
Do the rules have to be written in the HTML?
No. The JSON can also be delivered from a separate file referenced by an HTTP response header, which is useful when you cannot edit the page template. Inline is simplest when you control the template.
If your site feels slow between pages and you want to know why, send us the address and we will tell you what we see.