---
title: What are Speculation Rules?
date: 2026-04-15
tags:
  - web-platform
  - performance
  - chrome
description: A short mental model for the Speculation Rules API and when
  prerendering is actually worth it.
url: https://kevinkiklee.io/posts/what-are-speculation-rules
---

> Placeholder post — written to exercise rendering paths during development.
> Will be replaced before launch.

Speculation Rules is a browser API that lets a page declare which URLs the user is likely to visit next, so the browser can prefetch or even fully prerender them in the background. Think of it as a structured replacement for `<link rel="prefetch">` with explicit eagerness levels and document-rules support.

## What problem does it solve?

Navigation is the slowest part of most sites. By the time the user clicks, the network round-trip, parse, and paint are all still ahead. Speculation Rules moves that work earlier — the browser does it during idle time, gated by your hints.

## How do you declare rules?

Drop a JSON script in the document head. The browser parses it once and uses it for the lifetime of the page.

```html
<script type="speculationrules">
{
  "prerender": [
    {
      "where": { "href_matches": "/posts/*" },
      "eagerness": "moderate"
    }
  ]
}
</script>
```

The `eagerness` levels are `immediate`, `eager`, `moderate`, and `conservative`. Most sites should start at `moderate` — the browser only prerenders when the user shows clear intent (e.g., hovers a link).

## When should you NOT prerender?

Prerendering executes the target page's JavaScript. That means analytics fire, side-effect-heavy server actions run, and any non-idempotent code on first paint will misbehave.

Skip prerendering for:

- pages with login-side-effects or token rotation
- analytics dashboards that count page views on render
- anything that mutates server state on initial GET (which you shouldn't be doing anyway)

## How does it compare to `<link rel="prerender">`?

| Feature        | `<link rel="prerender">` | Speculation Rules |
| -------------- | ------------------------ | ----------------- |
| Status         | Deprecated               | Active            |
| Granularity    | Single URL               | URL patterns      |
| Eagerness      | Implicit                 | Explicit          |
| Document rules | No                       | Yes               |

The old `<link rel="prerender">` was removed in favour of this API precisely because it had no eagerness control and burnt the user's data plan.

## Further reading

- [Speculation Rules explainer](https://github.com/WICG/nav-speculation/blob/main/triggers.md)
- [Chrome Status entry](https://chromestatus.com/feature/5740655119761408)

Lorem ipsum dolor sit amet, consectetur adipiscing elit. This trailing paragraph exists so the post has enough body text to test the reading-time estimate, the related-posts sidebar, and the prose stylesheet's vertical rhythm under longer flows.