# Insert speculation rules (insert_speculation_rules)

Injects a same-origin prefetch speculation-rules script. The insert_speculation_rules filter: what it does, its risks and the directives.

Canonical URL: https://modpagespeed.com/docs/filters/insert_speculation_rules/

- Category: HTML
- CoreFilters: No
- OptimizeForBandwidth: No
- Risk: Test first

Injects a same-origin prefetch `<script type="speculationrules">` block so that supporting browsers prefetch a link as the visitor starts interacting with it; browsers without speculation-rules support ignore the tag. Only same-origin links are eligible.

## How it works

The filter stands down in several cases rather than injecting a ruleset that would be wasted or unsafe: it backs off when the page already carries its own speculation ruleset, when a `Content-Security-Policy` forbids inline scripts, on non-200 responses, on cookie-setting responses, on `no-store` responses, and on AMP documents.

The injected ruleset is fixed: one rule that prefetches same-origin document URLs (`href_matches: "/*"`) with `eagerness: moderate`, meaning the browser applies its own heuristic for when a prefetch is worth starting rather than prefetching every link on sight. There is no prerender and nothing cross-origin. The script is placed at the end of `<body>`. Requests that negotiate markdown (`Accept: text/markdown`), such as AI-agent fetches, are also left clean: they run no scripts and get no benefit, so the tag stays out of the variant those caches key on under `Vary: Accept`.

Speculative prefetch spends origin bandwidth on navigations that may never happen, so treat it as a trade-off and test it against your own traffic. This filter is opt-in and is not part of any rewrite level.

## When to use it

- Not in CoreFilters: it runs only when you enable it by name.
- Risk rating on these docs: **Test first**.

## Risks

The [HTML filters](https://modpagespeed.com/docs/html-filters/#insert_speculation_rules) page lists no specific risks for this filter. If a page misbehaves with it, `DisableFilters insert_speculation_rules` turns it off for the scope you set it in.

## Configuration

Enable it in the module configuration, at server, virtual-host or location scope:

**Apache**

```apache
ModPagespeedEnableFilters insert_speculation_rules
```

**nginx**

```nginx
pagespeed EnableFilters insert_speculation_rules;
```

**IIS (pagespeed.config)**

```text
pagespeed EnableFilters insert_speculation_rules
```

Scoping, `ForbidFilters` and the thresholds filters read: [Choosing filters](https://modpagespeed.com/docs/filter-selection/).

## Live example

See the before and after, with the source diff: [insert_speculation_rules example](https://modpagespeed.com/examples/insert_speculation_rules/).

## Frequently asked questions

**What does the insert_speculation_rules filter do?**

Injects a same-origin prefetch `<script type="speculationrules">` block so that supporting browsers prefetch a link as the visitor starts interacting with it; browsers without speculation-rules support ignore the tag. Only same-origin links are eligible.

**Is insert_speculation_rules enabled by default?**

No. `insert_speculation_rules` is not in CoreFilters, the default RewriteLevel; it runs only when you enable it by name with `EnableFilters`.

**How do I enable insert_speculation_rules on Apache and nginx?**

Add `ModPagespeedEnableFilters insert_speculation_rules` on Apache or `pagespeed EnableFilters insert_speculation_rules;` on nginx. On IIS, add `pagespeed EnableFilters insert_speculation_rules` to pagespeed.config.

## Related filters

- [`add_base_tag`](https://modpagespeed.com/docs/filters/add_base_tag/): Add base tag
- [`add_head`](https://modpagespeed.com/docs/filters/add_head/): Add head
- [`add_ids`](https://modpagespeed.com/docs/filters/add_ids/): Add IDs
- [`add_instrumentation`](https://modpagespeed.com/docs/filters/add_instrumentation/): Add instrumentation
- [`collapse_whitespace`](https://modpagespeed.com/docs/filters/collapse_whitespace/): Collapse whitespace
- [`combine_heads`](https://modpagespeed.com/docs/filters/combine_heads/): Combine heads
- [`compute_statistics`](https://modpagespeed.com/docs/filters/compute_statistics/): Compute HTML statistics
- [`convert_meta_tags`](https://modpagespeed.com/docs/filters/convert_meta_tags/): Convert meta tags

This page is drawn from the [insert_speculation_rules entry on HTML filters](https://modpagespeed.com/docs/html-filters/#insert_speculation_rules). Every filter in one table: [PageSpeed filters](https://modpagespeed.com/docs/filters/).