2026 Speculation Rules API for static multi-page HTML: prefetch, prerender, and Safari-ready guardrails on Mac

Static marketing sites still feel instant only when the next navigation is already warm. The Speculation Rules API lets you attach a JSON policy beside your HTML so the browser can prefetch or even prerender likely destinations without bolting a client-side router onto an otherwise classic multi-page application. In 2026, the practical question is no longer “can we hint?” but “how do we hint without tripping Content-Security-Policy, doubling CDN bills, or prerendering pages that mutate user-visible state?” This guide answers that with numeric guardrails, a decision matrix, and a rehearsal workflow on Apple Silicon Safari where scheduling differs from Chromium.

Pair this article with Subresource Integrity and CSP for CDN scripts because speculation hints often pull the same origins your CSP already governs, and with responsive images and LCP hygiene so prefetch traffic does not accidentally promote oversized hero assets on cold navigations.

Speculation rules JSON primer

At a high level you publish a <script type="speculationrules"> block containing JSON objects the browser parses eagerly—often in the first kilobytes of your shell layout. Each rule set declares where hints apply (current document patterns), what to warm (target URLs), and how eager the action should be. Unlike classic link rel=prefetch tags scattered through templates, speculation rules centralize policy so performance engineers can diff them in Git and attach owners.

Teams that ship twelve or fewer primary conversion paths—pricing, signup, docs hubs—benefit most because you can cap hints per page and reason about cache heat explicitly. Treat every hinted URL like a mini-release: it should tolerate being fetched twice (once speculated, once navigated) without double-counting business events unless your analytics layer deduplicates pageload beacons.

Document rules versus list rules

Document rules describe conditions under which the user agent may speculate based on the current URL, referrer, or other predicates exposed by the platform. They pair naturally with marketing sites that bucket traffic by campaign query strings—think utm_medium=paid—without hard-coding every landing permutation into list rules. List rules enumerate explicit URLs and remain useful for footer-heavy navigation grids where the same twelve links repeat on every page.

When you mix both, resolve conflicts up front: document rules should win for mobile profiles where you want fewer destinations, while desktop list rules can widen coverage slightly. Document that decision in your performance playbook so a well-meaning contributor does not append a second script tag that doubles hints silently.

Prefetch versus prerender decision matrix

Use the matrix below before enabling prerender. Numbers reflect conservative starting points we use when auditing static sites in 2026; adjust after measuring your own CDN logs.

Hint type	CPU cost	Risk to analytics	Typical first-week cap	Best targets
Prefetch document	Low	Low if navigation dedupes	4 concurrent hints	Pricing, docs index, changelog
Prefetch list	Low–medium	Medium on strict beacon vendors	6 URLs per page	Footer hubs, cross-locale switches
Prerender	High	High—JS may run	1 URL on mobile, 2 on desktop	Anonymous marketing funnels only

Prerender is seductive because Largest Contentful Paint appears to vanish, yet it is also where teams accidentally execute third-party A/B snippets twice or fire duplicate lead pixels. If a page contains localStorage writes, OAuth callbacks, or personalized hero text, keep it on prefetch-only hints until you refactor side effects behind navigation gates.

CSP, credentials, and crossorigin pitfalls

Prefetch traffic still obeys Content-Security-Policy. If your connect-src whitelist forgets the CDN hostname that serves JSON for dynamic modules, hints fail closed and you waste bytes shipping a rule the browser cannot apply. Mirror every hinted origin across script-src, img-src, and font-src as needed, and keep hashes or nonces aligned with the article referenced above.

Credential policy matters: marketing pages that mix SameSite=Lax session cookies with prerender can create confusing “ghost” sessions if the prerendered document mutates storage. Prefer requires: ["anonymous"]-style constraints for public pages, and isolate authenticated apps on separate registrable domains when possible. Document the decision in your security review so auditors know prerender is intentionally blocked for signed-in surfaces.

Metrics that catch naive rollouts

Track four indicators during the first seven days after enabling hints: total egress gigabytes per thousand sessions, median LCP on navigations that consumed a hint, Interaction to Next Paint on the sending page (because speculative work steals main-thread time), and error rates on downstream APIs that suddenly see anticipatory traffic. A healthy rollout often shows egress rise by 3–8% while LCP improves by 150–400 ms on hinted paths; anything beyond double-digit egress growth deserves a second look at caps.

Instrument hinted navigations with a boolean flag in your RUM provider so analysts can separate “lucky prefetch hits” from organic cold loads. Without that split, product teams misread conversion lifts and bake misleading expectations into quarterly plans.

Safari and WebKit rehearsal

Chromium-class browsers led speculation rules, yet Safari remains a mandatory sign-off channel for macOS-heavy audiences—designers, iOS-first product managers, and regulated industries that standardize on WebKit for privacy reviews. Treat unsupported or partially supported configurations as progressive enhancement: HTML must render correctly, analytics must tolerate missing hints, and CSP must stay strict even when the browser ignores speculative work.

Rehearse on a dedicated Apple Silicon Mac mini with stable Safari plus a pinned WebKit Technology Preview build when your policy uses newer predicates. Network Quality Estimator behaviors and cache partitioning differ from Linux-based CI agents, so synthetic tests that pass in headless Chromium can still regress in Safari’s scheduler. Capture screen recordings of the first navigation after hover-heavy interactions; Safari coalesces pointer-driven updates differently than Windows laptops used by many developers.

Drop-in patterns for static MPAs

For hand-authored static exports, colocate a single speculation JSON fragment in your layout partial and vary it with build-time data—locale prefixes, campaign slugs—so translators cannot accidentally fork CSP-sensitive URLs. Keep the JSON under 2 KB gzip on mobile shells; larger blobs compete with hero HTML for the first round trip.

When you internationalize, duplicate the rule block per locale directory instead of pointing French hints at English pricing. Cross-locale mistakes inflate bounce rates more than missing hints ever would. Pair each locale’s hints with hreflang correctness so speculation traffic never lands on the wrong language variant.

FAQ

Does Speculation Rules replace link rel=preload?

No—preload targets critical subresources on the current document, while speculation rules optimize future navigations. You still need preload or fetchpriority for the hero image on the page the user already opened.

Is prerender safe for authenticated dashboards?

Generally unsafe: prerender executes JavaScript and may trigger side effects. Keep dashboards off prerender lists until your app architecture isolates anonymous shells.

Will Safari honor speculation rules in 2026?

Capabilities evolve; test continuously and never assume parity with Chromium. Unsupported browsers should still deliver a first-class experience.

How many concurrent prefetches should I allow?

Start with two to four concurrent hints on mobile profiles, then scale after weekly CDN and RUM reviews.

Shipping speculation rules is ultimately an operations problem: you need real hardware, real Safari, and enough unified memory to keep devtools, screen capture, and the browser profile resident without swapping. A rented Mac mini on MacHTML gives you that environment for roughly $16.9 per day—far cheaper than rushing a wrong prerender policy to production and spending engineering weeks unwinding duplicate client events. Apple Silicon stays quiet under sustained prefetch workloads, matches the machines your stakeholders actually use, and exposes the same TCC and networking stack as their laptops, which keeps surprises out of release checklists.

Elastic rental windows mean you can spin up a WebKit rehearsal host for the sprint when speculation rules land, then tear it down once metrics flatten—no capex, no idle metal in a closet, and no guessing whether Linux CI faithfully models Safari scheduling.