From de3167eb0e008f171b692aec3096978e840ab7cd Mon Sep 17 00:00:00 2001 From: Dave McCabe Date: Fri, 1 Dec 2023 19:45:28 -0800 Subject: [PATCH 1/2] Initial docs for Float functions: preconnect, prefetchDNS, preinit, preinitModule, preload, preloadModule --- src/content/reference/react-dom/index.md | 13 ++ src/content/reference/react-dom/preconnect.md | 89 ++++++++++ .../reference/react-dom/prefetchDNS.md | 89 ++++++++++ src/content/reference/react-dom/preinit.md | 120 +++++++++++++ .../reference/react-dom/preinitModule.md | 93 ++++++++++ src/content/reference/react-dom/preload.md | 160 ++++++++++++++++++ .../reference/react-dom/preloadModule.md | 94 ++++++++++ src/sidebarReference.json | 24 +++ 8 files changed, 682 insertions(+) create mode 100644 src/content/reference/react-dom/preconnect.md create mode 100644 src/content/reference/react-dom/prefetchDNS.md create mode 100644 src/content/reference/react-dom/preinit.md create mode 100644 src/content/reference/react-dom/preinitModule.md create mode 100644 src/content/reference/react-dom/preload.md create mode 100644 src/content/reference/react-dom/preloadModule.md diff --git a/src/content/reference/react-dom/index.md b/src/content/reference/react-dom/index.md index fb5fd48b06a..8bb274b7234 100644 --- a/src/content/reference/react-dom/index.md +++ b/src/content/reference/react-dom/index.md @@ -17,6 +17,19 @@ These APIs can be imported from your components. They are rarely used: * [`createPortal`](/reference/react-dom/createPortal) lets you render child components in a different part of the DOM tree. * [`flushSync`](/reference/react-dom/flushSync) lets you force React to flush a state update and update the DOM synchronously. +## Resource Preloading APIs {/*resource-preloading-apis*/} + +These APIs can be used to make apps faster by pre-loading resources such as scripts, stylesheets, and fonts as soon as you know you need them, for example before navigating to another page where the resources will be used: + +* [`preload`](/reference/react-dom/preload) lets you fetch a stylesheet, font, image, or external script that you expect to use. +* [`preloadModule`](/reference/react-dom/preloadModule) lets you fetch an ESM module that you expect to use. +* [`preinit`](/reference/react-dom/preinit) lets you fetch and evaluate an external script or fetch and insert a stylesheet. +* [`preinitModule`](/reference/react-dom/preinitModule) lets you fetch and evaluate an ESM module. +* [`prefetchDNS`](/reference/react-dom/prefetchDNS) lets you prefetch the IP address of a DNS domain name that you expect to connect to. +* [`preconnect`](/reference/react-dom/preconnect) lets you connect to a server you expect to request resources from, even if you don't know what resources you'll need yet. + + + --- ## Entry points {/*entry-points*/} diff --git a/src/content/reference/react-dom/preconnect.md b/src/content/reference/react-dom/preconnect.md new file mode 100644 index 00000000000..89039f3e9c8 --- /dev/null +++ b/src/content/reference/react-dom/preconnect.md @@ -0,0 +1,89 @@ +--- +title: preconnect +--- + + + +`preconnect` lets you eagerly connect to a server that you expect to load resources from. + +```js +preconnect("https://example.com"); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preconnect(href)` {/*preconnect*/} + +To preconnect to a host, call the `preconnect` function from `react-dom`. + +```js +import { preconnect } from 'react-dom'; + +function AppRoot() { + preconnect("https://example.com"); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preconnect` function provides the browser with a hint that it should open a connection to the given server. If the browser chooses to do so, this can speed up the loading of resources from that server. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the server you want to connect to. + + +#### Returns {/*returns*/} + +`preconnect` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preconnect` with the same server have the same effect as a single call. +* In the browser, you can call `preconnect` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preconnect` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. +* If you know the specific resources you'll need, you can call [other functions](/reference/react-dom/#resource-preloading-apis) instead that will start loading the resources right away. +* There is no benefit to preconnecting to the same server the webpage itself is hosted from because it's already been connected to by the time the hint would be given. + +--- + +## Usage {/*usage*/} + +### Preconnecting when rendering {/*preconnecting-when-rendering*/} + +Call `preconnect` when rendering a component if you know that its children will load external resources from that host. + +```js +import { preconnect } from 'react-dom'; + +function AppRoot() { + preconnect("https://example.com"); + return ...; +} +``` + +### Preconnecting in an event handler {/*preconnecting-in-an-event-handler*/} + +Call `preconnect` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preconnect } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preconnect('http://example.com'); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/prefetchDNS.md b/src/content/reference/react-dom/prefetchDNS.md new file mode 100644 index 00000000000..42920fd0ccb --- /dev/null +++ b/src/content/reference/react-dom/prefetchDNS.md @@ -0,0 +1,89 @@ +--- +title: prefetchDNS +--- + + + +`prefetchDNS` lets you eagerly look up the IP of a server that you expect to load resources from. + +```js +prefetchDNS("https://example.com"); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `prefetchDNS(href)` {/*prefetchdns*/} + +To look up a host, call the `prefetchDNS` function from `react-dom`. + +```js +import { prefetchDNS } from 'react-dom'; + +function AppRoot() { + prefetchDNS("https://example.com"); + // ... +} + +``` + +[See more examples below.](#usage) + +The prefetchDNS function provides the browser with a hint that it should look up the IP address of a given server. If the browser chooses to do so, this can speed up the loading of resources from that server. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the server you want to connect to. + +#### Returns {/*returns*/} + +`prefetchDNS` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `prefetchDNS` with the same server have the same effect as a single call. +* In the browser, you can call `prefetchDNS` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `prefetchDNS` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. +* If you know the specific resources you'll need, you can call [other functions](/reference/react-dom/#resource-preloading-apis) instead that will start loading the resources right away. +* There is no benefit to prefetching the same server the webpage itself is hosted from because it's already been looked up by the time the hint would be given. +* Compared with [`preconnect`](/reference/react-dom/preconnect), `prefetchDNS` may be better if you are speculatively connecting to a large number of domains, in which case the overhead of preconnections might outweigh the benefit. + +--- + +## Usage {/*usage*/} + +### Prefetching DNS when rendering {/*prefetching-dns-when-rendering*/} + +Call `prefetchDNS` when rendering a component if you know that its children will load external resources from that host. + +```js +import { prefetchDNS } from 'react-dom'; + +function AppRoot() { + prefetchDNS("https://example.com"); + return ...; +} +``` + +### Prefetching DNS in an event handler {/*prefetching-dns-in-an-event-handler*/} + +Call `prefetchDNS` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { prefetchDNS } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + prefetchDNS('http://example.com'); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preinit.md b/src/content/reference/react-dom/preinit.md new file mode 100644 index 00000000000..a2bbfc3b450 --- /dev/null +++ b/src/content/reference/react-dom/preinit.md @@ -0,0 +1,120 @@ +--- +title: preinit +--- + + + +`preinit` lets you eagerly fetch and evaluate a stylesheet or external script. + +```js +preinit("https://example.com/script.js", {as: "style"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preinit(href, options)` {/*preinit*/} + +To preinit a script or stylesheet, call the `preinit` function from `react-dom`. + +```js +import { preinit } from 'react-dom'; + +function AppRoot() { + preinit("https://example.com/script.js", {as: "script"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preinit` function provides the browser with a hint that it should start downloading and executing the given resource, which can save time. Scripts that you `preinit` are executed when they finish downloading. Stylesheets that you preinit are inserted into the document, which causes them to go into effect right away. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the resource you want to download and execute. +* `options`: an object. It contains the following properties: + * `as`: a required string. The type of resource. Its possible values are `script` and `style`. + * `precedence`: a string. Required with stylesheets. Says where to insert the stylesheet relative to others. Stylesheets with higher precedence can override those with lower precedence. The possible values are `reset`, `low`, `medium`, `high`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. It is required when `as` is set to `"fetch"`. + * `integrity`: a string. A cryptographic hash of the resource, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `nonce`: a string. A cryptographic [nonce to allow the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + * `fetchPriority`: a string. Suggests a relative priority for fetching the resource. The possible values are `auto` (the default), `high`, and `low`. + +#### Returns {/*returns*/} + +`preinit` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preinit` with the same `href` have the same effect as a single call. +* In the browser, you can call `preinit` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preinit` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preiniting when rendering {/*preiniting-when-rendering*/} + +Call `preinit` when rendering a component if you know that it or its children will use a specific resource, and you're OK with the resource being evaluated and thereby taking effect immediately upon being downloaded. + + + +#### Preiniting an external script {/*preiniting-an-external-script*/} + +```js +import { preinit } from 'react-dom'; + +function AppRoot() { + preinit("https://example.com/script.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to download the script but not to execute it right away, use [`preload`](/reference/react-dom/preload) instead. If you want to load an ESM module, use [`preinitModule`](/reference/react-dom/preinitModule). + + + +#### Preiniting a stylesheet {/*preiniting-a-stylesheet*/} + +```js +import { preinit } from 'react-dom'; + +function AppRoot() { + preinit("https://example.com/style.css", {as: "style", precedence: "medium"}); + return ...; +} +``` + +The `precedence` option, which is required, lets you control the order of stylesheets within the document. Stylesheets with higher precedence can overrule those with lower precedence. + +If you want to download the stylesheet but not to insert it into the document right away, use [`preload`](/reference/react-dom/preload) instead. + + + + + +### Preiniting in an event handler {/*preiniting-in-an-event-handler*/} + +Call `preinit` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preinit } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preinit("https://example.com/wizardStyles.css", {as: "style"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preinitModule.md b/src/content/reference/react-dom/preinitModule.md new file mode 100644 index 00000000000..fc90749b8a4 --- /dev/null +++ b/src/content/reference/react-dom/preinitModule.md @@ -0,0 +1,93 @@ +--- +title: preinitModule +--- + + + +`preinitModule` lets you eagerly fetch and evaluate an ESM module. + +```js +preinitModule("https://example.com/module.js", {as: "script"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preinitModule(href, options)` {/*preinitmodule*/} + +To preinit an ESM module, call the `preinitModule` function from `react-dom`. + +```js +import { preinitModule } from 'react-dom'; + +function AppRoot() { + preinitModule("https://example.com/module.js", {as: "script"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preinitModule` function provides the browser with a hint that it should start downloading and executing the given module, which can save time. Modules that you `preinit` are executed when they finish downloading. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the module you want to download and exeucute. +* `options`: an object. It contains the following properties: + * `as`: a required string. It must be `'script'`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. + * `integrity`: a string. A cryptographic hash of the module, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `nonce`: a string. A cryptographic [nonce to allow the module](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + +#### Returns {/*returns*/} + +`preinitModule` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preinitModule` with the same `href` have the same effect as a single call. +* In the browser, you can call `preinitModule` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preinitModule` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preloading when rendering {/*preloading-when-rendering*/} + +Call `preinitModule` when rendering a component if you know that it or its children will use a specific module and you're OK with the module being evaluated and thereby taking effect immediately upon being downloaded. + +```js +import { preinitModule } from 'react-dom'; + +function AppRoot() { + preinitModule("https://example.com/module.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to download the module but not to execute it right away, use [`preloadModule`](/reference/react-dom/preloadModule) instead. If you want to preinit a script that isn't an ESM module, use [`preinit`](/reference/react-dom/preinit). + +### Preloading in an event handler {/*preloading-in-an-event-handler*/} + +Call `preinitModule` in an event handler before transitioning to a page or state where the module will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preinitModule } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preinitModule("https://example.com/module.js", {as: "script"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preload.md b/src/content/reference/react-dom/preload.md new file mode 100644 index 00000000000..c05cd9fb29a --- /dev/null +++ b/src/content/reference/react-dom/preload.md @@ -0,0 +1,160 @@ +--- +title: preload +--- + + + +`preload` lets you eagerly fetch a resource such as a stylesheet, font, or external script that you expect to use. + +```js +preload("https://example.com/font.woff2", {as: "font"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preload(href, options)` {/*preload*/} + +To preload a resource, call the `preload` function from `react-dom`. + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/font.woff2", {as: "font"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preload` function provides the browser with a hint that it should start downloading the given resource, which can save time. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the resource you want to download. +* `options`: an object. It contains the following properties: + * `as`: a required string. The type of resource. Its possible values are `audio`, `document`, `embed`, `fetch`, `font`, `image`, `object`, `script`, `style`, `track`, `video`, `worker`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. It is required when `as` is set to `"fetch"`. + * `referrerPolicy`: a string. The [Referrer header](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#referrerpolicy) to send when fetching. Its possible values are `no-referrer-when-downgrade` (the default), `no-referrer`, `origin`, `origin-when-cross-origin`, and `unsafe-url`. + * `integrity`: a string. A cryptographic hash of the resource, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `type`: a string. The MIME type of the resource. + * `nonce`: a string. A cryptographic [nonce to allow the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + * `fetchPriority`: a string. Suggests a relative priority for fetching the resource. The possible values are `auto` (the default), `high`, and `low`. + * `imageSrcSet`: a string. For use only with `as: "image"`. Specifies the [source set of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). + * `imageSizes`: a string. For use only with `as: "image"`. Specifies the [sizes of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). + + + +#### Returns {/*returns*/} + +`preload` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple equivalent calls to `preload` have the same effect as a single call. Calls to `preload` are considered equivalent according to the following rules: + * Two calls are equivalent if they have the same `href`, except: + * If `as` is set to `image`, two calls are equivalent if they have the same `href`, `imageSrcSet`, and `imageSizes`. +* In the browser, you can call `preload` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preload` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preloading when rendering {/*preloading-when-rendering*/} + +Call `preload` when rendering a component if you know that it or its children will use a specific resource. + + + +#### Preloading an external script {/*preloading-an-external-script*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/script.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to start executing the script immediately (rather than just downloading it), use [`preinit`](/reference/react-dom/preinit) instead. If you want to load an ESM module, use [`preloadModule`](/reference/react-dom/preloadModule). + + + +#### Preloading a stylesheet {/*preloading-a-stylesheet*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/style.css", {as: "style"}); + return ...; +} +``` + +If you want the stylesheet to be inserted into the document immediately (which means the browser will start parsing it immediately rather than just downloading it), use [`preinit`](/reference/react-dom/preinit) instead. + + + +#### Preloading a font {/*preloading-a-font*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/style.css", {as: "style"}); + preload("https://example.com/font.woff2", {as: "font"}); + return ...; +} +``` + +If you preload a stylesheet, it's smart to also preload any fonts that the stylesheet refers to. That way, the browser can start downloading the font before it's downloaded and parsed the stylesheet. + + + +#### Preloading an image {/*preloading-an-image*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("/banner.png", { + as: "image", + imageSrcSet: "/banner512.png 512w, /banner1024.png 1024w", + imageSizes: "(max-width: 512px) 512px, 1024px", + }); + return ...; +} +``` + +When preloading an image, the `imageSrcSet` and `imageSizes` options help the browser [fetch the correctly sized image for the size of the screen]((https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)). + + + + + +### Preloading in an event handler {/*preloading-in-an-event-handler*/} + +Call `preload` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preload } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preload("https://example.com/wizardStyles.css", {as: "style"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preloadModule.md b/src/content/reference/react-dom/preloadModule.md new file mode 100644 index 00000000000..abf563c0b2c --- /dev/null +++ b/src/content/reference/react-dom/preloadModule.md @@ -0,0 +1,94 @@ +--- +title: preloadModule +--- + + + +`preloadModule` lets you eagerly fetch an ESM module that you expect to use. + +```js +preloadModule("https://example.com/module.js", {as: "script"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preloadModule(href, options)` {/*preloadmodule*/} + +To preload an ESM module, call the `preloadModule` function from `react-dom`. + +```js +import { preloadModule } from 'react-dom'; + +function AppRoot() { + preloadModule("https://example.com/module.js", {as: "script"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preloadModule` function provides the browser with a hint that it should start downloading the given module, which can save time. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the module you want to download. +* `options`: an object. It contains the following properties: + * `as`: a required string. It must be `'script'`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. + * `integrity`: a string. A cryptographic hash of the module, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `nonce`: a string. A cryptographic [nonce to allow the module](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + + +#### Returns {/*returns*/} + +`preloadModule` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preloadModule` with the same `href` have the same effect as a single call. +* In the browser, you can call `preloadModule` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preloadModule` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preloading when rendering {/*preloading-when-rendering*/} + +Call `preloadModule` when rendering a component if you know that it or its children will use a specific module. + +```js +import { preloadModule } from 'react-dom'; + +function AppRoot() { + preloadModule("https://example.com/module.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to start executing the module immediately (rather than just downloading it), use [`preinitModule`](/reference/react-dom/preinitModule) instead. If you want to load a script that isn't an ESM module, use [`preload`](/reference/react-dom/preload). + +### Preloading in an event handler {/*preloading-in-an-event-handler*/} + +Call `preloadModule` in an event handler before transitioning to a page or state where the module will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preloadModule } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preloadModule("https://example.com/module.js", {as: "script"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 6272569370c..f06fe558b14 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -201,6 +201,30 @@ "title": "hydrate", "path": "/reference/react-dom/hydrate" }, + { + "title": "preconnect", + "path": "/reference/react-dom/preconnect" + }, + { + "title": "prefetchDNS", + "path": "/reference/react-dom/prefetchDNS" + }, + { + "title": "preinit", + "path": "/reference/react-dom/preinit" + }, + { + "title": "preinitModule", + "path": "/reference/react-dom/preinitModule" + }, + { + "title": "preload", + "path": "/reference/react-dom/preload" + }, + { + "title": "preloadModule", + "path": "/reference/react-dom/preloadModule" + }, { "title": "render", "path": "/reference/react-dom/render" From 8eb2dfd77c4b62a87349f55bb19055c82d58eb4b Mon Sep 17 00:00:00 2001 From: David McCabe Date: Mon, 18 Dec 2023 15:46:16 -0800 Subject: [PATCH 2/2] Incorporated feedback --- src/content/reference/react-dom/index.md | 10 +++++----- src/content/reference/react-dom/preconnect.md | 7 +++++++ src/content/reference/react-dom/prefetchDNS.md | 7 +++++++ src/content/reference/react-dom/preinit.md | 13 +++++++++++++ .../reference/react-dom/preinitModule.md | 13 +++++++++++++ src/content/reference/react-dom/preload.md | 17 ++++++++++++++--- .../reference/react-dom/preloadModule.md | 13 +++++++++++++ src/sidebarReference.json | 18 ++++++++++++------ 8 files changed, 84 insertions(+), 14 deletions(-) diff --git a/src/content/reference/react-dom/index.md b/src/content/reference/react-dom/index.md index 8bb274b7234..80fd58facd0 100644 --- a/src/content/reference/react-dom/index.md +++ b/src/content/reference/react-dom/index.md @@ -19,16 +19,16 @@ These APIs can be imported from your components. They are rarely used: ## Resource Preloading APIs {/*resource-preloading-apis*/} -These APIs can be used to make apps faster by pre-loading resources such as scripts, stylesheets, and fonts as soon as you know you need them, for example before navigating to another page where the resources will be used: +These APIs can be used to make apps faster by pre-loading resources such as scripts, stylesheets, and fonts as soon as you know you need them, for example before navigating to another page where the resources will be used. +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call these APIs yourself. Consult your framework's documentation for details. + +* [`prefetchDNS`](/reference/react-dom/prefetchDNS) lets you prefetch the IP address of a DNS domain name that you expect to connect to. +* [`preconnect`](/reference/react-dom/preconnect) lets you connect to a server you expect to request resources from, even if you don't know what resources you'll need yet. * [`preload`](/reference/react-dom/preload) lets you fetch a stylesheet, font, image, or external script that you expect to use. * [`preloadModule`](/reference/react-dom/preloadModule) lets you fetch an ESM module that you expect to use. * [`preinit`](/reference/react-dom/preinit) lets you fetch and evaluate an external script or fetch and insert a stylesheet. * [`preinitModule`](/reference/react-dom/preinitModule) lets you fetch and evaluate an ESM module. -* [`prefetchDNS`](/reference/react-dom/prefetchDNS) lets you prefetch the IP address of a DNS domain name that you expect to connect to. -* [`preconnect`](/reference/react-dom/preconnect) lets you connect to a server you expect to request resources from, even if you don't know what resources you'll need yet. - - --- diff --git a/src/content/reference/react-dom/preconnect.md b/src/content/reference/react-dom/preconnect.md index 89039f3e9c8..cb14a5e89b1 100644 --- a/src/content/reference/react-dom/preconnect.md +++ b/src/content/reference/react-dom/preconnect.md @@ -1,7 +1,14 @@ --- title: preconnect +canary: true --- + + +The `preconnect` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + `preconnect` lets you eagerly connect to a server that you expect to load resources from. diff --git a/src/content/reference/react-dom/prefetchDNS.md b/src/content/reference/react-dom/prefetchDNS.md index 42920fd0ccb..f9889836ee7 100644 --- a/src/content/reference/react-dom/prefetchDNS.md +++ b/src/content/reference/react-dom/prefetchDNS.md @@ -1,7 +1,14 @@ --- title: prefetchDNS +canary: true --- + + +The `prefetchDNS` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + `prefetchDNS` lets you eagerly look up the IP of a server that you expect to load resources from. diff --git a/src/content/reference/react-dom/preinit.md b/src/content/reference/react-dom/preinit.md index a2bbfc3b450..5a04528bd6e 100644 --- a/src/content/reference/react-dom/preinit.md +++ b/src/content/reference/react-dom/preinit.md @@ -1,7 +1,20 @@ --- title: preinit +canary: true --- + + +The `preinit` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + `preinit` lets you eagerly fetch and evaluate a stylesheet or external script. diff --git a/src/content/reference/react-dom/preinitModule.md b/src/content/reference/react-dom/preinitModule.md index fc90749b8a4..ba6316a7a16 100644 --- a/src/content/reference/react-dom/preinitModule.md +++ b/src/content/reference/react-dom/preinitModule.md @@ -1,7 +1,20 @@ --- title: preinitModule +canary: true --- + + +The `preinitModule` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + `preinitModule` lets you eagerly fetch and evaluate an ESM module. diff --git a/src/content/reference/react-dom/preload.md b/src/content/reference/react-dom/preload.md index c05cd9fb29a..ffec1177c07 100644 --- a/src/content/reference/react-dom/preload.md +++ b/src/content/reference/react-dom/preload.md @@ -1,7 +1,20 @@ --- title: preload +canary: true --- + + +The `preload` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + `preload` lets you eagerly fetch a resource such as a stylesheet, font, or external script that you expect to use. @@ -40,7 +53,7 @@ The `preload` function provides the browser with a hint that it should start dow * `href`: a string. The URL of the resource you want to download. * `options`: an object. It contains the following properties: - * `as`: a required string. The type of resource. Its possible values are `audio`, `document`, `embed`, `fetch`, `font`, `image`, `object`, `script`, `style`, `track`, `video`, `worker`. + * `as`: a required string. The type of resource. Its [possible values](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#as) are `audio`, `document`, `embed`, `fetch`, `font`, `image`, `object`, `script`, `style`, `track`, `video`, `worker`. * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. It is required when `as` is set to `"fetch"`. * `referrerPolicy`: a string. The [Referrer header](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#referrerpolicy) to send when fetching. Its possible values are `no-referrer-when-downgrade` (the default), `no-referrer`, `origin`, `origin-when-cross-origin`, and `unsafe-url`. * `integrity`: a string. A cryptographic hash of the resource, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). @@ -50,8 +63,6 @@ The `preload` function provides the browser with a hint that it should start dow * `imageSrcSet`: a string. For use only with `as: "image"`. Specifies the [source set of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). * `imageSizes`: a string. For use only with `as: "image"`. Specifies the [sizes of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). - - #### Returns {/*returns*/} `preload` returns nothing. diff --git a/src/content/reference/react-dom/preloadModule.md b/src/content/reference/react-dom/preloadModule.md index abf563c0b2c..05333f1cb71 100644 --- a/src/content/reference/react-dom/preloadModule.md +++ b/src/content/reference/react-dom/preloadModule.md @@ -1,7 +1,20 @@ --- title: preloadModule +canary: true --- + + +The `preloadModule` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + `preloadModule` lets you eagerly fetch an ESM module that you expect to use. diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 893d9f61758..5c9ad86fa67 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -243,27 +243,33 @@ }, { "title": "preconnect", - "path": "/reference/react-dom/preconnect" + "path": "/reference/react-dom/preconnect", + "canary": true }, { "title": "prefetchDNS", - "path": "/reference/react-dom/prefetchDNS" + "path": "/reference/react-dom/prefetchDNS", + "canary": true }, { "title": "preinit", - "path": "/reference/react-dom/preinit" + "path": "/reference/react-dom/preinit", + "canary": true }, { "title": "preinitModule", - "path": "/reference/react-dom/preinitModule" + "path": "/reference/react-dom/preinitModule", + "canary": true }, { "title": "preload", - "path": "/reference/react-dom/preload" + "path": "/reference/react-dom/preload", + "canary": true }, { "title": "preloadModule", - "path": "/reference/react-dom/preloadModule" + "path": "/reference/react-dom/preloadModule", + "canary": true }, { "title": "render",