Body

Summary

Deprecate @astrojs/prefetch and provide first-class prefetch support in Astro.

Initial implementation: withastro/astro#8951

Background & Motivation

With the introduction of View Transitions, it includes partial prefetching code for snappy navigation between pages. We can take this opportunity to support prefetching in core, and share the prefetch behaviour with View Transitions.

I've started an implementation before an RFC as the initial plan was to simply move @astrojs/prefetch to core. However, it would also be a good time to polish up and extend the API.

Similar discussion: #661

Goals

• An option to enable prefetching
• Enable prefetching via an attribute/hint
• Enable prefetching for all links by default (required by View transitions)
• Disable prefetching if all links are enabled by default
• Different prefetching strategies (click, hover, viewport, etc)
• Only add JS if using prefetching
• (IMO) Opinionated prefetching, not too many options

Example

Based on the implementation currently (withastro/astro#8951), the usage looks like this:

<!-- prefetch defaults to hover -->
<a href="/foo" data-astro-prefetch>foo</a>

<!-- prefetch on tap (touchstart, mousedown events) -->
<a href="/foo" data-astro-prefetch="tap">foo</a>

<!-- prefetch on hover (focusin, focusout, mouseenter, mouseleave events) -->
<a href="/foo" data-astro-prefetch="hover">foo</a>

<!-- prefetch on enter viewport (IntersectionObserver) -->
<a href="/foo" data-astro-prefetch="viewport">foo</a>

<!-- disable prefetch if prefetch all by default -->
<a href="/foo" data-astro-prefetch="false">foo</a>

You can also configure options in astro.config.js:

prefetch: {
  // Whether to prefetch all links by default. same as adding `data-astro-prefetch` to all links.
  // Default false, but true if view transitions is used. User can explicitly set this to false
  // to disable for view transitions. (I tried coming up a better name)
  prefetchAll: true,
  // Default prefetch strategy for `data-astro-prefetch` (no value specified).
  defaultStrategy: 'hover' // accepts 'tap' and 'viewport' too
}

Boolean options also work:

// enable prefetch with default configuration
prefetch: true,
// disable prefetch explicitly (e.g. if you're using View transitions, set this to `false`
// to really disable prefetch)
prefetch: false

Different prefetch strategies have different behaviours and opinions:

• tap: Calls fetch() on touchstart or mousedown events (they are called before click event)
• hover: Calls fetch() on focusin+focusout or mouseenter+mouseleave events. Hover detection kicks in after 80ms delay.
• viewport: Creates a <link rel="prefetch"> on enter viewport. It has lower priority than fetch() to not clog up the request. Intersection detection kicks in after 300ms.

Notes: hover and viewport only works on <a /> tags on initial page load (and view transition page load) due to limitations of the events. Unless we watch the entire DOM with MutationObserver but it's not performant.

For programmatic usage, we can also support:

import { prefetch } from 'astro:prefetch'

prefetch('http://...', { with: 'link' }) // second parameter optional, can specify link/fetch for prefetch priority