Documentation / Smart prefetching
Smart prefetching
Warm the browser cache for explicitly marked links on hover, keyboard focus, or viewport entry, with cancellation and reduced-data awareness.
Fetch before a navigation
Smart prefetching starts a speculative GET when a marked link receives sustained hover or keyboard focus, or becomes visible. It warms the browser's HTTP cache. A later native or HTMX navigation can reuse that response when its cache policy and request headers allow it.
No separate JavaScript response cache is used. Cache-Control: no-store still prevents reuse, no-cache still requires revalidation, and Vary still separates representations. Prefetching never changes the DOM, pushes history, or executes a response's scripts. Only mark URLs whose GET is safe to run before a user clicks.
Enable and mark links
Enable on the root app during setup, after your middleware and before serving traffic. The call is idempotent and works before or after other routes have been registered:
app := hyperchi.NewFromEnv()
app.Use(app.Middleware.Default()...)
if err := app.EnablePrefetch(); err != nil {
log.Fatal(err)
}
Put the helper after htmx in the full-page layout. It emits a deferred external script at /hyperchi/js/prefetch.js:
<script defer src="/static/htmx.js"></script>
{{prefetchScript}}
<a href="/guides" data-hc-prefetch="hover">Guides</a>
<a href="/about" data-hc-prefetch="viewport">About</a>
<a href="/articles" data-hc-prefetch="both">Articles</a>
hover includes keyboard focus. viewport starts when the link actually enters the viewport, without a look-ahead margin. both enables either strategy. Each waits 100 milliseconds before fetching. An unmarked link is never prefetched, and data-hc-prefetch="off" on a link or ancestor opts that subtree out. Other strategy values are ignored.
Go renderers can call app.PrefetchScript(). Without EnablePrefetch, the helper is empty and no prefetch middleware or endpoint is installed. The runtime can also be served directly from frontend/assets/scripts/hyperchi-prefetch.js; in that case your server must provide the appropriate Vary headers itself.
Cache policy and HTMX
The server must opt responses into useful caching. For content safe to reuse for one minute in the current browser, a handler can set:
app.Get("/guides", func(c *hyperchi.Context) error {
c.SetHeader("Cache-Control", "private, max-age=60")
return c.View("guides", hyperchi.H{"title": "Guides"})
})
Choose freshness according to your content. An account page that must reflect a recent mutation may need no-cache or no-store. The runtime clears its speculative queue when HTMX starts a non-GET/HEAD request; it cannot invalidate the browser's HTTP cache after a write. Do not make cacheable responses depend on stale session state.
Ordinary HTMX 4 GET links are supported:
<a href="/guides" hx-get="/guides" hx-target="#content"
data-hc-prefetch="hover">Guides</a>
<div id="content"></div>
<nav hx-boost:inherited="true">
<a href="/articles" data-hc-prefetch="viewport">Articles</a>
</nav>
The runtime sends the standard HTMX request headers for these links, including full/partial request type and source/target identifiers. It supports boolean boost, simple #id or body targets, default data-hx- aliases, and explicit :inherited attributes. It also follows htmx's implicitInheritance setting. The actual navigation remains entirely under HTMX's control.
EnablePrefetch adds Vary for HX-Request, HX-Request-Type, HX-Boosted, HX-Target, HX-Source, and HX-Current-URL. Those values are retained even if an inner middleware replaces Vary before writing. Handlers must still declare any additional request headers they vary on, such as Accept or custom authorization/context headers. Different sources, targets, or current URLs can therefore require distinct cached responses.
Links with dynamic/custom request attributes such as hx-headers, hx-vals, hx-include, hx-config, hx-confirm, non-GET methods, appended inheritance, or inline HTMX event handlers are skipped. Custom HTMX prefixes/meta characters and extended target expressions are not supported. Global application request hooks cannot be predicted: opt out links whose requests depend on them. See the official HTMX event guide for the request lifecycle.
Budgets and cancellation
The runtime uses these fixed limits:
- Two simultaneous speculative fetches, with at most 64 delayed/queued candidates.
- A five-second timeout and a one-MiB body limit per request.
- A 30-second attempt-deduplication window with at most 128 remembered request keys.
- At most 512 viewport candidates observed per scan.
Only same-origin HTTP(S) links are eligible. Downloads, links with ping, non-self targets, credential-bearing URLs, fragment-only links, the current page, and pages with a targeted <base> are skipped. Redirects are rejected, and only successful HTML responses are drained into the browser cache. Speculative requests use same-origin credentials, low fetch priority where supported, and Purpose: prefetch.
Leaving hover/focus or the viewport cancels work when no other strategy still wants that element. Clicking cancels that element's pending fetch so normal navigation can proceed. Removing a link, going offline, hiding the page, or requesting reduced data cancels pending work. An aborted or failed attempt is not retried immediately; the deduplication window prevents repeated speculative failures.
Prefetching is disabled for Save-Data, reported 2G/slow-2G connections, and prefers-reduced-data: reduce. Where the browser does not report connection preferences, those signals are unavailable. Without IntersectionObserver, hover and focus still work. New links inserted by HTMX swaps or ordinary DOM changes are scanned automatically.
For explicit lifecycle control:
window.HyperChiPrefetch.refresh(); // rescan links
window.HyperChiPrefetch.clear(); // cancel speculation and forget attempts
window.HyperChiPrefetch.stop(); // permanently stop this page's runtime
clear() does not clear the browser's HTTP cache. The runtime does not poll. Its observers and event handlers exist only after the script is included.
Keep going
The realtime guide covers updates after navigation. The developer toolbar helps inspect request patterns and timings while developing locally.