Modern web performance work has a slightly awkward problem: many of the biggest wins happen before a user clicks. If a browser can safely prepare the next page while intent is obvious, the navigation can feel immediate instead of merely fast.
That is the job of the Speculation Rules API. It gives developers a structured, browser-native way to tell supporting browsers which documents are reasonable candidates for prefetching or prerendering. In 2026, it is worth treating as a serious progressive enhancement for content sites, commerce journeys, and product flows, not as a universal switch to turn on everywhere.
TL;DR
The Speculation Rules API can prefetch likely next pages or prerender very likely next pages. Start with conservative prefetch rules for safe, same-origin navigations. Reserve prerendering for short, high-confidence journeys where the destination is safe to load before the user explicitly visits it. Measure both activation rate and wasted work, then make the rules more precise. The performance payoff can be excellent, but only when product semantics, analytics, authentication, and server costs are part of the design.
Table of contents
- What speculation rules actually do
- Prefetch versus prerender
- The safety review most teams skip
- A practical rollout for a Next.js or React app
- Handling analytics, API requests, and side effects
- Measuring whether the feature is helping
- Common mistakes
- FAQ
What the Speculation Rules API actually does
A speculation rule is JSON placed in a <script type="speculationrules"> element, or served as a separate resource through the Speculation-Rules HTTP header. The browser evaluates the rules and may prepare matching navigations when its own device, network, and user-preference heuristics allow it.
That last point matters. These are hints, not commands. A browser can decline to act because the device is under memory pressure, the connection is constrained, or the user has enabled a data-saving setting. That makes the API a good fit for progressive enhancement: your application must be correct and usable when no speculation occurs.
The two main operations have different costs:
- Prefetch downloads the destination document response in advance. It does not fully load and execute the page’s subresources.
- Prerender prepares the destination far more completely. The browser loads the document, its subresources, and JavaScript in a hidden context so that it can activate the page on navigation.
When a prerendered navigation is activated, the browser promotes that prepared page rather than starting a conventional navigation. The result can feel nearly instant. It is also why prerendering deserves much more care than prefetching.
Prefetch versus prerender: choose based on confidence and cost
A useful way to make this decision is to think in terms of intent confidence and destination cost.
| Situation | Better default | Why | | --- | --- | --- | | A user is reading an article with clear “next article” links | Prefetch | There may be several plausible choices, and fetching the document is relatively cheap. | | A checkout flow moves from address to payment after a valid form submission | Prerender, if safe | The next navigation is highly likely and the perceived speed matters. | | Search results with dozens of links | Usually neither, or targeted prefetch | Broad rules can create significant wasted traffic. | | A logged-in dashboard with live mutations | Conservative prefetch only | Loading the destination early can trigger unwanted requests or confusing state. | | A marketing site’s primary CTA path | Prerender after hover or visible intent | A small, predictable path is an ideal candidate. |
Prefetching is the lower-risk starting point. It has a smaller resource cost and is suitable for a broader set of pages. Prerendering can consume roughly the resources of rendering another page, so it should be reserved for destinations that are both likely and safe.
A helpful rule of thumb: prefetch pages people might visit, prerender pages they are overwhelmingly likely to visit next.
The safety review most teams skip
The hard part is not adding a JSON block. It is deciding whether a page can be loaded before a user has deliberately navigated to it.
Before adding any URL pattern to a prerender rule, ask these questions:
Does loading the page cause a side effect?
Some applications still perform mutations on page load: marking a notification read, reserving inventory, creating a draft record, refreshing a session, or emitting an email-tracking event. These are poor prerender candidates until the behaviour is changed.
Move irreversible work behind a user action, or defer it until the page is activated. A route should ideally be safe to render more than once, in the background, and never be seen.
Does the page make expensive server calls?
A dashboard route that fans out to five internal services may be expensive even if it has no visible side effect. If ten percent of prerenders are activated, ninety percent may be waste. Look at server and database costs, not only Core Web Vitals.
Is the destination personalised or permission-sensitive?
Be careful with account settings, billing, admin pages, and anything that displays sensitive data. Same-origin does not automatically mean low-risk. Ensure your authorization model remains correct, responses do not accidentally become cacheable across users, and observability distinguishes speculative requests from genuine visits.
Does the page assume it is visible?
Code that grabs focus, starts media, opens a modal, or immediately initializes a fragile third-party widget may behave badly during prerendering. Audit lifecycle assumptions in both first-party and third-party scripts.
A practical rollout for a Next.js or React app
Start with one user journey, not your entire route tree. A documentation site might choose related articles. A SaaS product might choose a stable onboarding step. A commerce site might choose a product detail page after a user hovers a card.
Here is a conservative document-level rule that prefetches internal links matching a selected area of a site:
<script type="speculationrules">
{
"prefetch": [
{
"where": {
"and": [
{ "href_matches": "/guides/*" },
{ "not": { "href_matches": "/guides/*?preview=*" } },
{ "not": { "selector_matches": "[rel~=nofollow]" } }
]
},
"eagerness": "moderate"
}
]
}
</script>The exact matching strategy should reflect your information architecture. Exclude preview pages, logout URLs, cart mutation links, and any route with unusual state semantics. Also exclude links you intentionally mark nofollow if that attribute reflects a link you do not want the browser to eagerly follow.
In Next.js, you can render the script in the root layout, ideally behind a small feature flag:
export function SpeculationRules() {
const rules = {
prefetch: [
{
where: {
and: [
{ href_matches: "/blog/*" },
{ not: { href_matches: "/blog/*?preview=*" } },
{ not: { selector_matches: "[rel~=nofollow]" } }
]
},
eagerness: "conservative"
}
]
};
return (
<script
type="speculationrules"
dangerouslySetInnerHTML={{ __html: JSON.stringify(rules) }}
/>
);
}Use JSON.stringify instead of hand-writing JSON in JSX, so escaping remains correct. If your Content Security Policy restricts inline scripts, explicitly allow inline speculation rules with the relevant CSP mechanism, such as the inline-speculation-rules source expression, a nonce, or a hash. Do not weaken a carefully designed CSP just to ship this feature.
For a higher-confidence route, add a very narrow prerender rule after the prefetch experiment has proven useful:
<script type="speculationrules">
{
"prerender": [
{
"where": {
"and": [
{ "href_matches": "/signup" },
{ "selector_matches": "a[data-primary-cta]" } }
]
},
"eagerness": "moderate"
}
]
}
</script>Keep the scope intentionally boring. A primary CTA is easier to understand, test, and measure than a site-wide guess about every link.
Handle analytics, API requests, and side effects explicitly
Speculation changes when a page runs, not just how quickly it appears. That has direct consequences for instrumentation.
First, identify speculative navigation requests on the server. Browsers can send a Sec-Purpose header, such as prefetch or prefetch;prerender. Log it where available and ensure speculative requests do not inflate pageview, conversion, or capacity metrics.
Second, make client-side analytics activation-aware. A pageview should represent a viewed page, not merely a hidden page that might be discarded. For prerender-capable experiences, defer view analytics until the document is visible and activated. The Page Visibility API and the prerenderingchange event are useful building blocks, but test against the browsers you support.
function trackVisiblePageview() {
if (document.prerendering) {
document.addEventListener("prerenderingchange", trackVisiblePageview, {
once: true,
});
return;
}
analytics.track("page_view", {
path: window.location.pathname,
});
}
trackVisiblePageview();Third, make data fetching idempotent. A GET request should not mutate state. That sounds obvious, yet older endpoints and third-party integrations sometimes violate it. Treat speculation as a useful test of whether your route is genuinely safe to render.
Measure whether the feature is helping
Do not declare victory because a lab test looks impressive. Production value comes from activated navigations, real user experience, and an acceptable waste rate.
Track at least these four metrics:
- Activation rate: What share of prefetched or prerendered destinations are actually visited?
- Navigation latency: Compare real-user navigation timing before and after the feature.
- Resource waste: Estimate transfer size, CPU work, and backend requests for speculative loads that are never activated.
- Business impact: For a key flow, watch completion rate and error rate, not only speed.
Segment the data by connection quality and device class. A strategy that improves desktop broadband sessions but burdens mobile users is not automatically a win. Browser heuristics may reduce harm, but your own rules still determine the opportunities presented to the browser.
Roll out behind a flag, start with a small percentage of traffic, and keep a kill switch. That discipline is especially important when the pages call internal APIs with meaningful cost.
Common mistakes
Treating speculation as a replacement for normal performance work
Speculation can hide latency for a successful next click. It does not fix a slow first load, a giant JavaScript bundle, or a poorly cached API. Continue reducing the cost of the destination itself.
Prerendering every internal link
This is a recipe for network, memory, and server waste. More rules are not better rules. Narrow, well-understood paths win.
Counting a prerender as a pageview
A hidden page is not a visit. Activation-aware analytics prevents inflated funnels and misleading A/B tests.
Ignoring CSP and framework output
A rule that works in a local prototype may be blocked in production by CSP, injected in the wrong part of the document, or duplicated by a layout. Verify the rendered HTML and browser console on a production-like environment.
Forgetting the fallback experience
Not every browser supports the API, and supporting browsers may decline a particular speculative load. The standard click path must remain fast and correct.
The bigger architectural lesson
The Speculation Rules API is part of a broader shift: performance is becoming more intent-aware. Instead of treating every navigation as an isolated cold start, the platform can use safe signals from the current document to prepare likely next work.
For teams, the important question is not “How do we prerender everything?” It is “Which next action is predictable enough, valuable enough, and safe enough to prepare early?” Answer that well, and the API becomes a precise tool for making a product feel more responsive without creating an invisible tax on every user.
Start with one route. Prefer prefetch. Instrument it. Then earn the right to prerender.
FAQ
Is the Speculation Rules API supported everywhere?
No. Treat it as progressive enhancement. Feature-detect where necessary, keep conventional navigation correct, and test the browsers that matter to your audience.
What is the difference between <link rel="prefetch"> and speculation rules?
Speculation rules express navigation intent to the browser and provide richer matching and eagerness controls. For supported browsers, they are generally the more appropriate primitive for document navigations.
Can I prerender authenticated pages?
Sometimes, but only after a careful safety and cost review. Ensure the route has no load-time side effects, protects data correctly, and does not create unacceptable backend work when users never navigate there.
Should I use prerendering for every CTA?
No. Use it only when the next destination is highly likely and valuable. Start with prefetching, measure activation, and expand conservatively.
How do I know whether a request was speculative?
On the server, inspect the Sec-Purpose request header where supported. In the browser, use prerender-aware lifecycle APIs to avoid running view-only work before activation.