Static Site Generators in Production

Instant Navigation with Speculation Rules

On a multi-page static site, every click starts from nothing: request the HTML, parse it, fetch the CSS, lay out, paint. Even from a nearby CDN edge that takes 400–800 ms on a phone, and readers pay it on every page. Single-page apps avoid it with a client-side router and a large JavaScript bundle. The Speculation Rules API avoids it with neither: the browser prerenders the page a reader is about to open — in a hidden tab, fully rendered — and swaps it in on click.

Static sites are the ideal case for this. Pages have no server-side side effects, so prerendering one the reader never opens costs only bandwidth, and pages are small, so that bandwidth is modest. This guide adds speculation rules to a 900-page docs site, handles analytics and exclusions, and measures the field result. It is part of Resource Hints and Navigation Speed.

Prerequisites

  • A static multi-page site. Sites with a client-side router (a Next.js export using <Link>, VitePress) already navigate client-side; speculation rules help less there.
  • Analytics you can modify, or that already handles prerendering.
  • Real-user monitoring that records navigationType, such as the web-vitals library — see Measuring INP on Static Sites with Real-User Monitoring.

How Prerendering Works

A speculation rule tells the browser which links are candidates and how eagerly to act on them. For prerender, the browser fetches the candidate page, runs its scripts, lays it out and paints it off-screen. When the reader clicks, the prerendered page is activated — shown instantly, with scripts already run. If the reader never clicks, the prerender is discarded.

Lifecycle of a prerendered page A reader hovers a link for 200 milliseconds, which triggers a prerender under moderate eagerness. The browser fetches, parses, lays out and paints the page off-screen over about 500 milliseconds while the reader is still deciding. On click, the prerendered page activates in about 40 milliseconds. If the reader moves on without clicking, the prerender is discarded. The work happens while the reader decides hover 200 ms intent signal prerender off-screen fetch · parse · layout · paint (~500 ms) click shown ~40 ms no click → discarded; cost is only the page's bytes 0 ms ~700 ms A typical hover-to-click delay on desktop is 300–900 ms, enough to finish most static pages
Moderate eagerness uses the gap between hover and click, which on desktop is usually long enough to prerender a static page completely.

Step 1: Add the Rules

Add a <script type="speculationrules"> block to the base layout. Document rules ("where") match links on the page, so the same block works on every template:

<script type="speculationrules">
{
  "prerender": [{
    "where": { "and": [
      { "href_matches": "/*" },
      { "not": { "href_matches": "/*.pdf" } },
      { "not": { "href_matches": "/downloads/*" } },
      { "not": { "selector_matches": "[data-no-prerender], [rel~=nofollow]" } }
    ]},
    "eagerness": "moderate"
  }],
  "prefetch": [{
    "where": { "href_matches": "/*" },
    "eagerness": "conservative"
  }]
}
</script>

The prerender rule covers same-origin links on hover; the prefetch rule is a fallback that at least fetches the HTML on pointer-down for links where prerender is not possible. Exclusions matter: downloads, logout links (if you have any authenticated section) and links to pages with heavy media should not be prerendered.

Step 2: Make Analytics Prerender-Aware

A prerendered page runs its scripts before the reader sees it. An analytics script that sends a page view on execution will count pages nobody viewed. Most modern analytics libraries handle this; for a first-party beacon, gate it:

function sendPageview() {
  navigator.sendBeacon('/api/pv', JSON.stringify({ path: location.pathname, ref: document.referrer }));
}
if (document.prerendering) {
  document.addEventListener('prerenderingchange', sendPageview, { once: true });
} else {
  sendPageview();
}

Do the same for anything with side effects or a cost per execution: A/B test assignment, ad requests, and any code that starts timers the reader would expect to begin when they arrive. Rendering code, including islands and component hydration, can run during prerender — that is the point.

Step 3: Verify It Works

Chrome DevTools' Application panel has a "Speculative loads" section listing the rules found, each candidate URL and its status: not triggered, running, ready, or failed with a reason. Hover a link for a moment, then check that its status becomes "Ready". Common failure reasons on static sites are cross-origin links (prerender is same-origin by default), pages that set Cache-Control: no-store, and memory limits on low-end devices.

In the field, the web-vitals library reports navigationType: 'prerender' for activated prerenders. Segment LCP by navigation type in your RUM data to see the effect directly, as described in Building a Core Web Vitals Dashboard from RUM Data.

Measured Impact

The 900-page docs site, two weeks before and after adding the rules. Field data from web-vitals beacons, Chrome only for the prerender rows since other browsers ignore the rules.

MeasureBeforeAfter
Internal navigations served by prerender (Chrome)0%71%
LCP p75, prerendered navigations—90 ms
LCP p75, all internal navigations (Chrome)980 ms310 ms
Median click-to-LCP, internal navigations (Chrome)620 ms40 ms
Extra bytes per session from unused prerenders (median)—38 KB
Origin requests per page view (CDN logs)1.001.19
Distribution of internal-navigation LCP before and after Two histograms of LCP for internal navigations in Chrome. Before, most navigations fall between 400 and 1,200 milliseconds with a p75 of 980. After, 71 percent of navigations fall in the first bucket under 100 milliseconds because they were prerendered, and the p75 drops to 310 milliseconds. Internal navigation LCP, share of navigations per bucket <100 100–400 400–800 800–1200 >1200 ms 71% prerendered before · p75 980 ms after · p75 310 ms web-vitals beacons, Chrome, two weeks each, ~140,000 internal navigations per period
Prerendered navigations collapse into the first bucket; the remaining 29% are touch navigations and links clicked too quickly to finish prerendering.

The cost side was small. Unused prerenders added a median of 38 KB per session — static pages with fingerprinted, already-cached assets are cheap to fetch twice — and the 19% increase in HTML requests at the CDN was served entirely from edge cache.

Touch Devices and Eagerness Tuning

Hover does not exist on touch screens, so moderate eagerness falls back to pointer-down, which gives only 80–150 ms of head start — enough to fetch the HTML but rarely to finish rendering. Two refinements recover some of that gap for mobile readers. First, for the one link most readers take next — the "next page" link at the bottom of a docs page, or the first result on an index — add an explicit list rule with eagerness: "eager", emitted per page by the generator:

<script type="speculationrules">
{ "prerender": [{ "urls": ["/guides/caching-hugo-builds/"], "eagerness": "eager" }] }
</script>
Head start before the click, by input type and rule Three bars showing how much time the browser has to prerender before activation. Desktop hover with moderate eagerness gives about 600 milliseconds, enough to finish. Touch with moderate eagerness gives about 120 milliseconds from pointer-down, not enough. An eager rule for the predicted next link starts on page load and gives many seconds. Time available to prerender before the click lands ~500 ms needed Desktop, moderate ~600 ms · finishes Touch, moderate ~120 ms · partial Touch, eager "next" from page load · finishes long before the tap Median hover-to-click and pointerdown-to-click intervals from RUM on the docs site
Touch readers need a prediction rather than an intent signal, which is why one eager rule per page pays off.

This prerenders that one page as soon as the current one loads. On the docs site, mobile readers followed the "next" link in 34% of sessions, and those navigations dropped from 710 ms to 60 ms click-to-LCP. Second, keep everything else at moderate: eager rules on every link would prerender dozens of pages per view on an index page, wasting bandwidth on metered connections. Chrome also disables speculation when Data Saver or battery saver is on, which is the right behaviour to leave in place.

Choosing the Predicted Page

The eager rule is only as good as its prediction. The simplest source is structure: docs sites have an explicit reading order, and a "next page" link derived from the sidebar is right more often than any heuristic. Blogs can use the most-followed related post, which is computable from a month of referrer data at build time — a small JSON file mapping each path to its most common next path, read by the layout. On the docs site, structural prediction was correct 34% of the time on mobile; referrer-based prediction on the blog was correct 22% of the time. Both are low enough that a wrong guess must be cheap, which for a static page with cached assets it is — a single HTML file of 15–40 KB.

Pitfalls & Rollback

  • Counting prerenders as page views. Gate analytics on prerenderingchange, or your traffic figures jump overnight.
  • Eager rules on link-heavy pages. An index with 200 links should never prerender eagerly. Use moderate by default and eager only for one or two predicted pages.
  • Side-effect URLs. Anything that changes state on GET — logout, unsubscribe, "mark as read" — must be excluded. Static sites rarely have them, but check.
  • no-store HTML. Pages served with Cache-Control: no-store are not prerendered in some cases. Static HTML should not need it.
  • Rollback: the feature is one script element. Removing it restores normal navigation on the next deploy; unsupported browsers were never affected.

Conclusion

Speculation rules give a multi-page static site app-like navigation without a client-side router: one script block in the base layout, prerender-aware analytics, and a few exclusions. On a 900-page docs site, 71% of Chrome's internal navigations were served from prerender, median click-to-LCP fell from 620 ms to 40 ms, and the cost was 38 KB of extra transfer per session. Add per-page eager rules for the obvious next link to extend the benefit to touch devices.

FAQ

Which browsers support speculation rules?

Chromium-based browsers, including Chrome and Edge, support prefetch and prerender via speculation rules. Other browsers ignore the script element, so adding rules never breaks anything; readers on unsupported browsers simply navigate normally.

What eagerness should a static site use?

Moderate for prerender. It starts after the pointer rests on a link for about 200 milliseconds, or on pointer-down on touch screens, which catches most clicks with little waste. Eager prerendering on load wastes bandwidth on pages with many links.

Will prerendering inflate my analytics?

It can if your analytics script records a page view as soon as it runs. Check document.prerendering and wait for the prerenderingchange event before sending the page view, so only pages the reader actually sees are counted.

How many pages can be prerendered at once?

Chrome limits concurrent prerenders; with moderate eagerness only a couple of recent candidates are kept, and older ones are discarded as new ones start. That limit is why moderate eagerness is both effective and cheap.