From f2ca0ec4411baea03875b1c11e30ec0d36f65e4a Mon Sep 17 00:00:00 2001 From: bluwy Date: Fri, 3 Nov 2023 17:52:16 +0800 Subject: [PATCH 1/3] Add prefetch docs phew --- src/content/docs/en/guides/prefetch.mdx | 173 ++++++++++++++++++++++++ src/i18n/en/nav.ts | 5 + 2 files changed, 178 insertions(+) create mode 100644 src/content/docs/en/guides/prefetch.mdx diff --git a/src/content/docs/en/guides/prefetch.mdx b/src/content/docs/en/guides/prefetch.mdx new file mode 100644 index 0000000000000..a4370158583cd --- /dev/null +++ b/src/content/docs/en/guides/prefetch.mdx @@ -0,0 +1,173 @@ +--- +title: Prefetch +description: Prefetch links for snappier navigation between pages. +i18nReady: true +--- + +Page load times play a big role in the usability and overall enjoyment of a site. Prefetching brings the benefits of near-instant page navigations to your multi-page application (MPA) by prefetching as you interact with the site. + +## Enable prefetching + +You can enable prefetching with the `prefetch` config: + +```js title="astro.config.js" ins={4} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + prefetch: true +}) +``` + +A prefetch script will be added to all pages of your site. You can then add the `data-astro-prefetch` attribute to any `` links on your site to opt-in to prefetching. When you hover over the link, the script will fetch the page in the background. + +Note that prefetching only works for links within your site, and not external links. + +## Prefetch configuration + +The `prefetch` config also accepts an option object to further customize prefetching. + +### Prefetch strategies + +Astro supports 3 prefetch strategies for various use cases: + +- `tap`: Prefetch just before you click on the link. +- `hover`: Prefetch when you hover over or focus on the link. (default) +- `viewport`: Prefetch as the links enter the viewport. + +You can specify a strategy for an individual link by passing it to the `data-astro-prefetch` attribute: + +```html +About +``` + +Each strategy is fine-tuned to only prefetch when needed and save your users' bandwidth. For example: + +- If the user 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), prefetching will be turned off. +- Quickly hovering or scrolling over links will not prefetch them. +- Links that use the `viewport` strategy are prefetched with a lower priority to not clog up the network. + +### Default prefetch strategy + +The default prefetch strategy when adding the `data-astro-prefetch` attribute is `hover`. To change it, you can configure [`prefetch.defaultStrategy`](/en/reference/configuration-reference#prefetchdefaultstrategy) in your `astro.config.js` file: + +```js title="astro.config.js" ins={4-6} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + prefetch: { + defaultStrategy: 'viewport' + } +}) +``` + +### Prefetch all links by default + +If you want to prefetch all links without needing the `data-astro-prefetch` attribute, you can set [`prefetch.prefetchAll`](/en/reference/configuration-reference#prefetchprefetchall) to `true`: + +```js title="astro.config.js" ins={4-6} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + prefetch: { + prefetchAll: true + } +}) +``` + +You can then opt-out of prefetching for individual links by setting `data-astro-prefetch="false"`: + +```html +About +``` + +The default prefetch strategy for all links can be changed with `prefetch.defaultStrategy` as shown in the [Default prefetch strategy section](#default-prefetch-strategy). + +## Prefetch programmatically + +As some navigation might not always appear as `` links, you can also prefetch programmatically with the `prefetch()` API from the `astro:prefetch` module: + +```astro + + + +``` + +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. + +Make sure to only import `prefetch()` in client-side scripts as it relies on browser APIs. + +## Using with View Transitions + +When you use [View Transitions](/en/guides/view-transitions/) on a page, prefetching will also be enabled by default. It sets a default configuration of `{ prefetchAll: true }` which enables [prefetching for all links](#prefetch-all-links-by-default) on the page. + +You can customize the prefetch configuration in `astro.config.js` to override the default. For example: + +```js title="astro.config.js" +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + // Disable prefetch completely + prefetch: false +}) +``` + +```js title="astro.config.js" +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + // Keep prefetch, but only prefetch for links with `data-astro-prefetch` + prefetch: { + prefetchAll: false + } +}) +``` + +## Migrating from `@astrojs/prefetch` + +Remove the `@astrojs/prefetch` integration and enable the `prefetch` config in `astro.config.js`: + +```js title="astro.config.js" ins={6} del={2,5} +import { defineConfig } from 'astro/config'; +import prefetch from '@astrojs/prefetch'; + +export default defineConfig({ + integrations: [prefetch()], + prefetch: true +}) +``` + +In `@astrojs/prefetch`, links selected by the [`selector`](/en/guides/integrations-guide/prefetch/#configselector) option prefetches as they enter the viewport. With the new prefetch feature, you should add `data-astro-prefetch="viewport"` to the links instead: + +```html + +``` + +In `@astrojs/prefetch`, links selected by the [`intentSelector`](/en/guides/integrations-guide/prefetch/#configintentselector) option prefetches as they are hovered over or focused. With the new prefetch feature, you should add `data-astro-prefetch` or `data-astro-prefetch="hover"` to the links instead: + +```html + + + + + +``` + +The [`throttles`](/en/guides/integrations-guide/prefetch/#configthrottles) option from `@astrojs/prefetch` is no longer needed as the new prefetch feature will automatically schedule and prefetch optimally. diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 68c3fdd3614c2..dce2049183275 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -63,6 +63,11 @@ export default [ slug: 'guides/view-transitions', key: 'guides/view-transitions', }, + { + text: 'Prefetch', + slug: 'guides/prefetch', + key: 'guides/prefetch', + }, { text: 'Add-ons', header: true, type: 'learn', key: 'addons' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, From b480e40187968cb0c081fa6c6a005b5d5385eb2d Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 8 Nov 2023 15:18:28 +0000 Subject: [PATCH 2/3] sarah editing pass --- src/content/docs/en/guides/prefetch.mdx | 64 +++++++++++++++---------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/src/content/docs/en/guides/prefetch.mdx b/src/content/docs/en/guides/prefetch.mdx index a4370158583cd..af45446f26d87 100644 --- a/src/content/docs/en/guides/prefetch.mdx +++ b/src/content/docs/en/guides/prefetch.mdx @@ -4,7 +4,7 @@ description: Prefetch links for snappier navigation between pages. i18nReady: true --- -Page load times play a big role in the usability and overall enjoyment of a site. Prefetching brings the benefits of near-instant page navigations to your multi-page application (MPA) by prefetching as you interact with the site. +Page load times play a big role in the usability and overall enjoyment of a site. Astro's **opt-in prefetching** brings the benefits of near-instant page navigations to your multi-page application (MPA) as your visitors interact with the site. ## Enable prefetching @@ -20,6 +20,10 @@ export default defineConfig({ A prefetch script will be added to all pages of your site. You can then add the `data-astro-prefetch` attribute to any `` links on your site to opt-in to prefetching. When you hover over the link, the script will fetch the page in the background. +```html + +``` + Note that prefetching only works for links within your site, and not external links. ## Prefetch configuration @@ -30,8 +34,8 @@ The `prefetch` config also accepts an option object to further customize prefetc Astro supports 3 prefetch strategies for various use cases: +- `hover` (default): Prefetch when you hover over or focus on the link. - `tap`: Prefetch just before you click on the link. -- `hover`: Prefetch when you hover over or focus on the link. (default) - `viewport`: Prefetch as the links enter the viewport. You can specify a strategy for an individual link by passing it to the `data-astro-prefetch` attribute: @@ -42,9 +46,9 @@ You can specify a strategy for an individual link by passing it to the `data-ast Each strategy is fine-tuned to only prefetch when needed and save your users' bandwidth. For example: -- If the user 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), prefetching will be turned off. +- 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), prefetching will be turned off. - Quickly hovering or scrolling over links will not prefetch them. -- Links that use the `viewport` strategy are prefetched with a lower priority to not clog up the network. +- Links that use the `viewport` strategy are prefetched with a lower priority to avoid clogging up the network. ### Default prefetch strategy @@ -62,7 +66,7 @@ export default defineConfig({ ### Prefetch all links by default -If you want to prefetch all links without needing the `data-astro-prefetch` attribute, you can set [`prefetch.prefetchAll`](/en/reference/configuration-reference#prefetchprefetchall) to `true`: +If you want to prefetch all links, including those without the `data-astro-prefetch` attribute, you can set [`prefetch.prefetchAll`](/en/reference/configuration-reference#prefetchprefetchall) to `true`: ```js title="astro.config.js" ins={4-6} import { defineConfig } from 'astro/config'; @@ -142,32 +146,40 @@ export default defineConfig({ ## Migrating from `@astrojs/prefetch` -Remove the `@astrojs/prefetch` integration and enable the `prefetch` config in `astro.config.js`: +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. -```js title="astro.config.js" ins={6} del={2,5} -import { defineConfig } from 'astro/config'; -import prefetch from '@astrojs/prefetch'; +1. Remove the `@astrojs/prefetch` integration and enable the `prefetch` config in `astro.config.js`: -export default defineConfig({ - integrations: [prefetch()], - prefetch: true -}) -``` + ```js title="astro.config.js" ins={6} del={2,5} + import { defineConfig } from 'astro/config'; + import prefetch from '@astrojs/prefetch'; -In `@astrojs/prefetch`, links selected by the [`selector`](/en/guides/integrations-guide/prefetch/#configselector) option prefetches as they enter the viewport. With the new prefetch feature, you should add `data-astro-prefetch="viewport"` to the links instead: + export default defineConfig({ + integrations: [prefetch()], + prefetch: true + }) + ``` -```html - -``` +2. Convert from `@astrojs/prefetch`'s configuration options: -In `@astrojs/prefetch`, links selected by the [`intentSelector`](/en/guides/integrations-guide/prefetch/#configintentselector) option prefetches as they are hovered over or focused. With the new prefetch feature, you should add `data-astro-prefetch` or `data-astro-prefetch="hover"` to the links instead: + - The deprecated integration used the `selector` config option to specify which links should be prefetched upon entering the viewport. + + Add `data-astro-prefetch="viewport"` to these individual links instead. -```html - - + ```html + + ``` - - -``` + - The deprecated integration used the `intentSelector` config option to specify which links should be prefetched when they were hovered over or focused. + + Add `data-astro-prefetch` or `data-astro-prefetch="hover"` to these individual links instead: + + ```html + + + + + + ``` -The [`throttles`](/en/guides/integrations-guide/prefetch/#configthrottles) option from `@astrojs/prefetch` is no longer needed as the new prefetch feature will automatically schedule and prefetch optimally. + - The [`throttles`](/en/guides/integrations-guide/prefetch/#configthrottles) option from `@astrojs/prefetch` is no longer needed as the new prefetch feature will automatically schedule and prefetch optimally. From 4b99eb220f6f21312fbcaa1ce9d71dca149b2636 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 9 Nov 2023 14:28:59 -0400 Subject: [PATCH 3/3] fix links --- 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 af45446f26d87..c831434d63e10 100644 --- a/src/content/docs/en/guides/prefetch.mdx +++ b/src/content/docs/en/guides/prefetch.mdx @@ -52,7 +52,7 @@ Each strategy is fine-tuned to only prefetch when needed and save your users' ba ### Default prefetch strategy -The default prefetch strategy when adding the `data-astro-prefetch` attribute is `hover`. To change it, you can configure [`prefetch.defaultStrategy`](/en/reference/configuration-reference#prefetchdefaultstrategy) in your `astro.config.js` file: +The default prefetch strategy when adding the `data-astro-prefetch` attribute is `hover`. To change it, you can configure [`prefetch.defaultStrategy`](/en/reference/configuration-reference/#prefetchdefaultstrategy) in your `astro.config.js` file: ```js title="astro.config.js" ins={4-6} import { defineConfig } from 'astro/config'; @@ -66,7 +66,7 @@ export default defineConfig({ ### Prefetch all links by default -If you want to prefetch all links, including those without the `data-astro-prefetch` attribute, you can set [`prefetch.prefetchAll`](/en/reference/configuration-reference#prefetchprefetchall) to `true`: +If you want to prefetch all links, including those without the `data-astro-prefetch` attribute, you can set [`prefetch.prefetchAll`](/en/reference/configuration-reference/#prefetchprefetchall) to `true`: ```js title="astro.config.js" ins={4-6} import { defineConfig } from 'astro/config'; @@ -182,4 +182,4 @@ The `@astrojs/prefetch` integration was deprecated in v3.5.0 and will eventually ``` - - The [`throttles`](/en/guides/integrations-guide/prefetch/#configthrottles) option from `@astrojs/prefetch` is no longer needed as the new prefetch feature will automatically schedule and prefetch optimally. + - The `throttles` option from `@astrojs/prefetch` is no longer needed as the new prefetch feature will automatically schedule and prefetch optimally.