v20.1.0

Reviewed By: evanyeung

Differential Revision: D79129481

fbshipit-source-id: 4b5fb017b4e8ba7101bf80323aaa0e301077dfcb

Author: lynnshaoyu

website/versioned_docs/version-v20.1.0/api-reference/entrypoint-apis/entrypoint-container.md

@@ -0,0 +1,38 @@
+---
+id: entrypoint-container
+title: EntryPointContainer
+slug: /api-reference/entrypoint-container/
+description: API reference for EntryPointContainer, a React component used to render the root component of an entrypoint
+keywords:
+  - entrypoint
+  - container
+  - root
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## `EntryPointContainer`
+
+<FbInternalOnly>
+
+For more information, see the [Defining EntryPoints](../../guides/entrypoints/using-entrypoints/#defining-entrypoints) and [Consuming EntryPoints](../../guides/entrypoints/using-entrypoints/#-entrypoints) guides.
+
+</FbInternalOnly>
+
+```js
+function EntryPointContainer({
+  entryPointReference,
+  props,
+}: {
+  +entryPointReference: PreloadedEntryPoint<TEntryPointComponent>,
+  +props: TRuntimeProps,
+}): ReactElement
+```
+
+A React component that renders a preloaded EntryPoint.
+
+* `entryPointReference`: the value returned from a call to `loadEntryPoint` or acquired from the `useEntryPointLoader` hook.
+* `props`: additional runtime props that will be passed to the `Component`
+
+<DocsRating />

website/versioned_docs/version-v20.1.0/api-reference/entrypoint-apis/load-entrypoint.md

@@ -0,0 +1,77 @@
+---
+id: load-entrypoint
+title: loadEntryPoint
+slug: /api-reference/load-entrypoint/
+description: API reference for loadEntryPoint, which imperatively loads an entrypoint and data for its queries
+keywords:
+  - entrypoint
+  - preload
+  - render-as-you-fetch
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## `loadEntryPoint`
+
+This function is designed to be used with `EntryPointContainer` to implement the "render-as-you-fetch" pattern.
+
+EntryPoint references returned from `loadEntryPoint` will leak data to the Relay store (if they have associated queries) unless `.dispose()` is called on them once they are no longer referenced. As such, prefer using `useEntryPointLoader` when possible, which ensures that EntryPoint references are correctly disposed for you. See the [`useEntryPointLoader`](../use-entrypoint-loader) docs for a more complete example.
+
+<FbInternalOnly>
+
+For more information, see the [Loading EntryPoints](../../guides/entrypoints/using-entrypoints/#loading-entrypoints) guide.
+
+</FbInternalOnly>
+
+```js
+const EntryPoint = require('MyComponent.entrypoint.js');
+
+const {loadQuery} = require('react-relay');
+
+// Generally, your component should access the environment from the React context,
+// and pass that environment to this function.
+const getEntrypointReference = environment => loadEntryPoint(
+  { getEnvironment: () => environment },
+  EntryPoint,
+  {id: '4'},
+);
+
+// later: pass entryPointReference to EntryPointContainer
+// Note that EntryPoint references should have .dispose() called on them,
+// which is missing in this example.
+```
+
+### Arguments
+
+* `environmentProvider`: A provider for a Relay Environment instance on which to execute the request. If you're starting this request somewhere within a React component, you probably want to use the environment you obtain from using [`useRelayEnvironment`](../use-relay-environment/).
+* `EntryPoint`: EntryPoint to load.
+* `entryPointParams`: Parameters that will be passed to the EntryPoint's `getPreloadProps` method.
+
+### Flow Type Parameters
+
+* `TEntryPointParams`: Type parameter corresponding to the type of the first parameter of the `getPreloadProps` method of the EntryPoint.
+* `TPreloadedQueries`: the type of the `queries` parameter to the EntryPoint component.
+* `TPreloadedEntryPoints`: the type of the `entrypoints` parameter passed to the EntryPoint component.
+* `TRuntimeProps`: the type of the `props` prop passed to `EntryPointContainer`. This object is passed down to the EntryPoint component, also as `props`.
+* `TExtraProps`: if an EntryPoint's `getPreloadProps` method returns an object with an `extraProps` property, those extra props will be passed to the EntryPoint component as `extraProps`.
+* `TEntryPointComponent`: the type of the EntryPoint.
+* `TEntryPoint`: the type of the EntryPoint.
+
+### Return Value
+
+An EntryPoint reference with the following properties:
+
+* `dispose`: a method that will release any query references loaded by this EntryPoint (including indirectly, by way of other EntryPoints) from being retained by the store. This can cause the data referenced by these query reference to be garbage collected.
+
+The exact format of the return value is *unstable and highly likely to change*. We strongly recommend not using any other properties of the return value, as such code would be highly likely to break when upgrading to future versions of Relay. Instead, pass the result of `loadEntryPoint()` to `EntryPointContainer`.
+
+### Behavior
+
+* When `loadEntryPoint()` is called, each of an EntryPoint's associated queries (if it has any) will load their query data and query AST. Once both the query AST and the data are available, the data will be written to the store. This differs from the behavior of `prepareEntryPoint_DEPRECATED`, which would only write the data from an associated query to the store when that query was rendered with `usePreloadedQuery`.
+* The EntryPoint reference's associated query references will be retained by the Relay store, preventing it the data from being garbage collected. Once you call `.dispose()` on the EntryPoint reference, the data from the associated queries is liable to be garbage collected.
+* `loadEntryPoint` may throw an error if it is called during React's render phase.
+
+
+
+<DocsRating />

website/versioned_docs/version-v20.1.0/api-reference/entrypoint-apis/use-entrypoint-loader.md

@@ -0,0 +1,99 @@
+---
+id: use-entrypoint-loader
+title: useEntryPointLoader
+slug: /api-reference/use-entrypoint-loader/
+description: API reference for useEntryPointLoader, a React hook used to load entrypoints in response to user events
+keywords:
+  - render-as-you-fetch
+  - entrypoint
+  - preload
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## `useEntryPointLoader`
+
+Hook used to make it easy to safely work with EntryPoints, while avoiding data leaking into the Relay store. It will keep an EntryPoint reference in state, and dispose of it when it is no longer accessible via state.
+
+<FbInternalOnly>
+
+For more information, see the [Loading EntryPoints](https://www.internalfb.com/intern/wiki/Relay/Guides/entry-points/#loading-entrypoints) guide.
+
+</FbInternalOnly>
+
+```js
+const {useEntryPointLoader, EntryPointContainer} = require('react-relay');
+
+const ComponentEntryPoint = require('Component.entrypoint');
+
+function EntryPointRevealer(): React.MixedElement {
+  const environmentProvider = useMyEnvironmentProvider();
+  const [
+    entryPointReference,
+    loadEntryPoint,
+    disposeEntryPoint,
+  ] = useEntryPointLoader(environmentProvider, ComponentEntryPoint);
+
+  return (
+    <>
+      {
+        entryPointReference == null && (
+          <Button onClick={() => loadEntryPoint({})}>
+            Click to reveal the contents of the EntryPoint
+          </Button>
+        )
+      }
+      {
+        entryPointReference != null && (
+          <>
+            <Button onClick={disposeEntryPoint}>
+              Click to hide and dispose the EntryPoint.
+            </Button>
+            <Suspense fallback="Loading...">
+              <EntryPointContainer
+                entryPointReference={entryPointReference}
+                props={{}}
+              />
+            </Suspense>
+          </>
+        )
+      }
+    </>
+  );
+}
+```
+
+### Arguments
+
+* `environmentProvider`: an object with a `getEnvironment` method that returns a Relay environment.
+* `EntryPoint`: the EntryPoint, usually acquired by importing a `.entrypoint.js` file.
+
+### Flow Type Parameters
+
+* `TEntryPointParams`: the type of the first argument to the `getPreloadProps` method of the EntryPoint.
+* `TPreloadedQueries`: the type of the `queries` prop passed to the EntryPoint component.
+* `TPreloadedEntryPoints`: the type of the `entryPoints` prop passed to the EntryPoint component.
+* `TRuntimeProps`: the type of the `props` prop passed to `EntryPointContainer`. This object is passed down to the EntryPoint component, also as `props`.
+* `TExtraProps`: if an EntryPoint's `getPreloadProps` method returns an object with an `extraProps` property, those extra props will be passed to the EntryPoint component as `extraProps` and have type `TExtraProps`.
+* `TEntryPointComponent`: the type of the EntryPoint component.
+* `TEntryPoint`: the type of the EntryPoint.
+
+### Return value
+
+A tuple containing the following values:
+
+* `entryPointReference`: the EntryPoint reference, or `null`.
+* `loadEntryPoint`: a callback that, when executed, will load an EntryPoint, which will be accessible as `entryPointReference`. If a previous EntryPoint was loaded, it will dispose of it. It may throw an error if called during React's render phase.
+    * Parameters
+        * `params: TEntryPointParams`: the params passed to the EntryPoint's `getPreloadProps` method.
+* `disposeEntryPoint`: a callback that, when executed, will set `entryPointReference` to `null` and call `.dispose()` on it. It has type `() => void`. It should not be called during React's render phase.
+
+### Behavior
+
+* When the `loadEntryPoint` callback is called, each of an EntryPoint's associated queries (if it has any) will load their query data and query AST. Once both the query AST and the data are available, the data will be written to the store. This differs from the behavior of `prepareEntryPoint_DEPRECATED`, which would only write the data from an associated query to the store when that query was rendered with `usePreloadedQuery`.
+* The EntryPoint reference's associated query references will be retained by the Relay store, preventing it the data from being garbage collected. Once you call `.dispose()` on the EntryPoint reference, the data from the associated queries is liable to be garbage collected.
+* The `loadEntryPoint` callback may throw an error if it is called during React's render phase.
+
+
+<DocsRating />