From 1d5181f3417e6991dcd0acae2dd023b7b4e92979 Mon Sep 17 00:00:00 2001 From: bluwy Date: Fri, 10 May 2024 18:14:26 +0800 Subject: [PATCH 1/4] Update prefetch docs with browser support information --- src/content/docs/en/guides/prefetch.mdx | 38 +++++++++++++++++-------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/src/content/docs/en/guides/prefetch.mdx b/src/content/docs/en/guides/prefetch.mdx index 5a13847e7ccc2..c51f9febb74b4 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,32 @@ export default defineConfig({ }); ``` +## Browser support + +Prefetching relies on [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch) if supported, or falls back to the [`fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). Below covers the common browsers which have subtle differences when prefetching: + +### Chrome + +1. It supports `` and will generally always work as expected. + +### Firefox + +1. It supports `` but errors with `NS_BINDING_ABORTED` if an explicit cache header like [`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) doesn't exist. +2. If it errors but the response have a proper [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header, it will be re-used on navigation. +3. Otherwise, if it errors with no other cache headers, the prefetch will not work. + +### Safari + +1. It doesn't support `` and will fall back to the `fetch()` API. +2. The `fetch()` API requires cache headers, like [`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 in order to work. Otherwise, the prefetch will not work. +3. 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 SSG or pre-rendered pages, the `ETag` header is often automatically set by the deployment platform, so they should work out of the box. + +For dynamic and server-side rendered pages, you should set the appropriate cache headers based on the page content. Visit the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) for more information on HTTP caching. + ## 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. From 36a05886fe9b11f0931d71d610fb68365dcd1c88 Mon Sep 17 00:00:00 2001 From: Bjorn Lu Date: Tue, 14 May 2024 23:29:22 +0800 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Sarah Rainsberger --- src/content/docs/en/guides/prefetch.mdx | 26 +++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/src/content/docs/en/guides/prefetch.mdx b/src/content/docs/en/guides/prefetch.mdx index c51f9febb74b4..502aa7fcda868 100644 --- a/src/content/docs/en/guides/prefetch.mdx +++ b/src/content/docs/en/guides/prefetch.mdx @@ -144,29 +144,35 @@ export default defineConfig({ ## Browser support -Prefetching relies on [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch) if supported, or falls back to the [`fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). Below covers the common browsers which have subtle differences when prefetching: +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 -1. It supports `` and will generally always work as expected. +**Support:** Chrome supports ``. Prefetching works as intended. ### Firefox -1. It supports `` but errors with `NS_BINDING_ABORTED` if an explicit cache header like [`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) doesn't exist. -2. If it errors but the response have a proper [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header, it will be re-used on navigation. -3. Otherwise, if it errors with no other cache headers, the prefetch will not work. +**Support:** 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 -1. It doesn't support `` and will fall back to the `fetch()` API. -2. The `fetch()` API requires cache headers, like [`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 in order to work. Otherwise, the prefetch will not work. -3. Edge case: `ETag` headers do not work in private windows. +**Support:** 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 SSG or pre-rendered pages, the `ETag` header is often automatically set by the deployment platform, so they should work out of the box. +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, so they should work out of the box. -For dynamic and server-side rendered pages, you should set the appropriate cache headers based on the page content. Visit the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) for more information on HTTP caching. +For dynamic and server-side rendered pages, you should set the appropriate cache headers 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` From f9bfc0a7c641b03f02127bcb23b4fc7533765d70 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 15 May 2024 16:07:42 +0800 Subject: [PATCH 3/4] Update docs --- src/content/docs/en/guides/prefetch.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/prefetch.mdx b/src/content/docs/en/guides/prefetch.mdx index 502aa7fcda868..058795b5a7f45 100644 --- a/src/content/docs/en/guides/prefetch.mdx +++ b/src/content/docs/en/guides/prefetch.mdx @@ -150,11 +150,11 @@ The most common browsers support Astro's prefetching with subtle differences: ### Chrome -**Support:** Chrome supports ``. Prefetching works as intended. +Chrome supports ``. Prefetching works as intended. ### Firefox -**Support:** Firefox supports `` but may display errors or fail entirely: +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. @@ -162,7 +162,7 @@ The most common browsers support Astro's prefetching with subtle differences: ### Safari -**Support:** 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. +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. From 247a580050ac4d9dc33449d1321592c441f30744 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 15 May 2024 12:01:39 -0300 Subject: [PATCH 4/4] replacing "should" --- src/content/docs/en/guides/prefetch.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/prefetch.mdx b/src/content/docs/en/guides/prefetch.mdx index 058795b5a7f45..33964f751158d 100644 --- a/src/content/docs/en/guides/prefetch.mdx +++ b/src/content/docs/en/guides/prefetch.mdx @@ -170,9 +170,9 @@ Safari does not support `` and will fall back to the `fetch 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, so they should work out of the box. +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, you should set the appropriate cache headers 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. +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`