Debug speculation rules with Chrome DevTools

Barry Pollard

Speculation rules can be used to prefetch and prerender next page navigations as detailed in the previous post. This can allow for much quicker—or even instant—page loads, greatly improving Core Web Vitals for these additional page navigations.

Debugging speculation rules can be tricky. This is particularly true for prerendered pages, as these pages are rendered in a separate renderer—kind of like a hidden background tab that replaces the current tab when activated. Therefore, the usual DevTools options cannot always be used to debug issues.

The Chrome team has been working hard to enhance DevTools support for speculation rules debugging. In this post, you'll see all the various ways of using these tools to understand a page's speculation rules, why they may not be working, and when developers can use the more familiar DevTools options—and when not.

Explanation of "pre-" terms

There's a lot of "pre-" terms that are confusing, so we'll start with an explanation of these:

  • Prefetch: fetching a resource or document in advance to improve future performance. This post covers prefetching documents using the Speculation Rules API, rather than the similar, but older <link rel="prefetch"> option often used for prefetching subresources.
  • Prerender: this goes a step beyond prefetching and actually renders the whole page as if the user had navigated to it, but keeps it in a hidden background renderer process ready to be used if the user actually navigates there. Again, this document is concerned with the newer Speculation Rules API version of this, rather than the older <link rel="prerender"> option (which no longer does a full prerender).
  • Speculative navigations: the collective term for the new prefetch and prerender options triggered by speculation rules.
  • Preload: an overloaded term that can refer to a number of technologies and processes including <link rel="preload">, the preload scanner, and service worker navigation preloads. These items won't be covered here, but the term is included to clearly differentiate those from the "speculative navigations" term.

Speculation rules for prefetch

Speculation rules can be used to prefetch the next navigation's document. For example, when inserting the following JSON into a page, next.html and next2.html will be prefetched:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "source": "list",
        "urls": ["next.html", "next2.html"],
        "tag": "rule-set-tag-1"
      }
    ]
  }
</script>

Using speculation rules for navigation prefetches has some advantages over the older <link rel="prefetch"> syntax, such as a more expressive API and the results being stored in memory cache rather than the HTTP disk cache.

Debug prefetch speculation rules

Prefetches triggered by speculation rules can be seen in the Network panel in the same way as other fetches: