diff --git a/src/content/docs/en/guides/prefetch.mdx b/src/content/docs/en/guides/prefetch.mdx index 5a13847e7ccc2..33964f751158d 100644 --- a/src/content/docs/en/guides/prefetch.mdx +++ b/src/content/docs/en/guides/prefetch.mdx @@ -51,7 +51,6 @@ Each strategy is fine-tuned to only prefetch when needed and save your users' ba - If a visitor is using [data saver mode](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData) or has a [slow connection](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType), prefetch will fallback to the `tap` strategy. - Quickly hovering or scrolling over links will not prefetch them. -- Links that use the `viewport` or `load` strategy are prefetched with a lower priority to avoid clogging up the network. ### Default prefetch strategy @@ -106,17 +105,6 @@ As some navigation might not always appear as `` links, you can also prefet ``` -You can additionally configure the priority of prefetching by passing the `with` option: - -```js -// Prefetch with `fetch()`, which has a higher priority. -prefetch('/about', { with: 'fetch' }); - -// Prefetch with ``, which has a lower priority -// and manually scheduled by the browser. (default) -prefetch('/about', { with: 'link' }); -``` - The `prefetch()` API includes the same [data saver mode](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData) and [slow connection](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType) detection so that it only prefetches when needed. To ignore slow connection detection, you can use the `ignoreSlowConnection` option: @@ -154,6 +142,38 @@ export default defineConfig({ }); ``` +## Browser support + +Astro's prefetching uses [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch) if supported by the browser, and falls back to the [`fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) otherwise. + +The most common browsers support Astro's prefetching with subtle differences: + +### Chrome + +Chrome supports ``. Prefetching works as intended. + +### Firefox + +Firefox supports `` but may display errors or fail entirely: + + - Without an explicit cache header (e.g. [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) or [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires)), prefetching will error with `NS_BINDING_ABORTED`. +- Even in the event of an error, if the response has a proper [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header, it will be re-used on navigation. +- Otherwise, if it errors with no other cache headers, the prefetch will not work. + +### Safari + +Safari does not support `` and will fall back to the `fetch()` API which requires cache headers (e.g. [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control), [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires), and [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)) to be set. Otherwise, the prefetch will not work. + +**Edge case:** `ETag` headers do not work in private windows. + +### Recommendations + +To best support all browsers, make sure your pages have the proper cache headers. + +For static or prerendered pages, the `ETag` header is often automatically set by the deployment platform and is expected to work out of the box. + +For dynamic and server-side rendered pages, set the appropriate cache headers yourself based on the page content. Visit the [MDN documentation on HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) for more information. + ## Migrating from `@astrojs/prefetch` The `@astrojs/prefetch` integration was deprecated in v3.5.0 and will eventually be removed entirely. Use the following instructions to migrate to Astro's built-in prefetching which replaces this integration.