Speculative Loading (Speculation Rules API)

ZiziCache implements the Speculation Rules API to prefetch or prerender likely navigation targets in supported browsers. Rules are injected into the page head on the frontend when enabled.

Modes and eagerness

• Prefetch – fetches resources in the background.
• Prerender – renders the full page in the background for instant activation.
• Off – disables speculative loading.
• Eagerness controls when the browser should act (for example: conservative, moderate, eager). Default is moderate.

Targeting and exclusions

• Rules are generated for same-origin paths only.
• Custom exclusions are supported (one pattern per line).
• ZiziCache automatically excludes WooCommerce dynamic pages (cart, checkout, account) and common localized variants.
• Optional conditional activation lets you enable speculation only on selected page types: home, front page, singular, archive, search.

Security and privacy requirements

• You can require HTTPS and/or anonymous client IP in the rules.
• These requirements are applied via the Speculation Rules requires attribute.

Analytics guard (prerender)

When analytics guard is enabled and you provide IDs (GA/Ads/Facebook Pixel/Clarity) or custom guard code, ZiziCache blocks those trackers during prerender using document.visibilityState === 'prerender'. This prevents duplicate page views.

Browser support

• Rules are injected only if HTMLScriptElement.supports('speculationrules') returns true.
• Unsupported browsers simply receive no rules (no errors).

Interaction with Quicklink

If Quicklink is enabled, it can act as a fallback when Speculation Rules are configured but not supported by the browser. See the Quicklink documentation for details.

Best practices

• Use prefetch for safety on dynamic sites, and reserve prerender for stable pages.
• Keep exclusions for login, checkout, and personalized pages.
• Start with moderate eagerness and adjust after testing.

Troubleshooting

• No effect: Confirm mode is not off, and the browser supports Speculation Rules.
• Too aggressive: Reduce eagerness or switch to prefetch.
• Unexpected pages: Add exclusions or enable conditional page targeting.