filter · HTML filters
Insert speculation rules (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
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
ModPagespeedEnableFilters insert_speculation_rulesnginx
pagespeed EnableFilters insert_speculation_rules;IIS (pagespeed.config)
pagespeed EnableFilters insert_speculation_rules
Scoping, ForbidFilters and the thresholds filters read:
Choosing filters
.
Live example
Injects a speculation-rules script so supporting browsers prefetch same-origin links a visitor is likely to open next.
This filter changes how the page is structured or delivered, not its size, so the example shows a source diff rather than a byte or request reduction.
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_rulesis not in CoreFilters, the default RewriteLevel; it runs only when you enable it by name withEnableFilters. - How do I enable insert_speculation_rules on Apache and nginx?
- Add
ModPagespeedEnableFilters insert_speculation_ruleson Apache orpagespeed EnableFilters insert_speculation_rules;on nginx. On IIS, addpagespeed EnableFilters insert_speculation_rulesto pagespeed.config.
Related filters
- add_base_tag — Add base tag
- add_head — Add head
- add_ids — Add IDs
- add_instrumentation — Add instrumentation
- collapse_whitespace — Collapse whitespace
- combine_heads — Combine heads
- compute_statistics — Compute HTML statistics
- convert_meta_tags — Convert meta tags
This page is drawn from the insert_speculation_rules entry on HTML filters. Every filter in one table: PageSpeed filters.