Initial docs for DOM static resource loading functions (#6459)

* Initial docs for Float functions: preconnect, prefetchDNS, preinit, preinitModule, preload, preloadModule

Author: davidmccabe

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.
+
+[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.
+
 ---
 
 ## Entry points {/*entry-points*/}

src/content/reference/react-dom/preconnect.md

@@ -0,0 +1,96 @@
+---
+title: preconnect
+canary: true
+---
+
+<Canary>
+
+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).
+
+</Canary>
+
+<Intro>
+
+`preconnect` lets you eagerly connect to a server that you expect to load resources from.
+
+```js
+preconnect("https://example.com");
+```
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## 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 (
+    <button onClick={onClick}>Start Wizard</button>
+  );
+}
+```

src/content/reference/react-dom/prefetchDNS.md

@@ -0,0 +1,96 @@
+---
+title: prefetchDNS
+canary: true
+---
+
+<Canary>
+
+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).
+
+</Canary>
+
+<Intro>
+
+`prefetchDNS` lets you eagerly look up the IP of a server that you expect to load resources from.
+
+```js
+prefetchDNS("https://example.com");
+```
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## 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 (
+    <button onClick={onClick}>Start Wizard</button>
+  );
+}
+```

src/content/reference/react-dom/preinit.md

@@ -0,0 +1,133 @@
+---
+title: preinit
+canary: true
+---
+
+<Canary>
+
+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).
+
+</Canary>
+
+<Note>
+
+[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.
+
+</Note>
+
+<Intro>
+
+`preinit` lets you eagerly fetch and evaluate a stylesheet or external script.
+
+```js
+preinit("https://example.com/script.js", {as: "style"});
+```
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## 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.
+
+<Recipes titleText="Examples of preiniting">
+
+#### 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).
+
+<Solution />
+
+#### 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.
+
+<Solution />
+
+</Recipes>
+
+### 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 (
+    <button onClick={onClick}>Start Wizard</button>
+  );
+}
+```