relay-runtime 20.1.1 → 21.0.1

package/llm-docs/guides/data-driven-dependencies/client-3d.mdx

@@ -0,0 +1,255 @@
+---
+id: client-3d
+title: Client 3D
+slug: /guides/data-driven-dependencies/client-3d/
+description: Client side data driven dependencies (3D)
+keywords:
+- 3D
+- Client 3D
+- data driven dependencies
+- module
+- match
+- MatchContainer
+---
+import {FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Use client 3D when all the data fields used to render your 3D components are resolved by client-side [Relay Resolvers](../../relay-resolvers/introduction/).
+
+## Example
+
+Here is an example of how Client 3D can be used in a React app.
+
+<FbInternalOnly>
+
+:::note
+For an example diff implementing Client 3D in www, see D62352682.
+:::
+
+</FbInternalOnly>
+
+### Schema
+You have an interface `IClient3D` that is a return type for a field on the query in your client schema extensions file:
+
+```graphql
+type Client3DData {
+  type: String!
+  info: String!
+}
+
+interface IClient3D {
+  id: ID!
+  data: Client3DData!
+}
+
+extend type Query {
+  client3D: IClient3D
+}
+```
+
+### Relay Resolvers
+You have 3 Relay Resolvers that return concrete objects that implement the `IClient3D` interface:
+
+<Tabs>
+  <TabItem value="1" label="Client3DBar" default>
+
+```ts
+export type Client3DModel = {
+  __id: DataID,
+};
+
+/**
+ * @relayType Client3DBar implements IClient3D
+ */
+function Client3DBar(id: DataID): ?Client3DModel {
+  if (id === INVALID_ID) {
+    return null;
+  }
+  return {
+    __id: id,
+  };
+}
+
+/**
+ * @relayField Client3DBar.data: Client3DData
+ */
+function data(client3DModel: Client3DModel): Client3DData {
+  return {
+    type: 'BAR',
+    info: 'someBarInfo',
+  }
+}
+```
+
+  </TabItem>
+  <TabItem value="2" label="Client3DFoo">
+
+```ts
+/**
+ * @relayType Client3DFoo implements IClient3D
+ */
+function Client3DFoo(id: DataID): ?Client3DModel {
+  if (id === INVALID_ID) {
+    return null;
+  }
+  return {
+    __id: id,
+  };
+}
+
+/**
+ * @relayField Client3DFoo.data: Client3DData
+ */
+function data(client3DModel: Client3DModel): Client3DData {
+  return {
+    type: 'FOO',
+    info: 'someFooInfo',
+  }
+}
+```
+
+  </TabItem>
+   <TabItem value="3" label="Client3DHelloWorld">
+
+```ts
+/**
+ * @relayType Client3DHelloWorld implements IClient3D
+ */
+function Client3DHelloWorld(id: DataID): ?Client3DModel {
+  if (id === INVALID_ID) {
+    return null;
+  }
+  return {
+    __id: id,
+  };
+}
+
+/**
+ * @relayField Client3DHelloWorld.data: Client3DData
+ */
+function data(client3DModel: Client3DModel): Client3DData {
+  return {
+    type: 'HELLO_WORLD',
+    info: 'someHelloWorldInfo',
+  }
+}
+```
+
+  </TabItem>
+</Tabs>
+
+
+### Component
+Before making use of Client 3D, your component will look something like this:
+```jsx
+component Client3DRelayRenderer() {
+  const CLIENT_3D_FRAGMENT = graphql`
+    fragment Client3DRelayRendererClient3DFragment on IClient3D {
+      data {
+        type
+        info
+      }
+    }
+  `;
+  const client3DData = useClientQuery(
+    graphql`
+      query Client3DRelayQuery {
+        client3D {
+          ...Client3DRelayRendererClient3DFragment
+        }
+      }
+    `
+  );
+
+  let component;
+  if (client3DData?.data?.type === 'FOO'):
+    component = <Client3DFooComponent data={client3DData.data} />
+  else if (client3DData?.data?.type === 'BAR'):
+    component = <Client3DBarComponent data={client3DData.data} />
+  else if (client3DData?.data?.type === 'HELLO_WORLD'):
+    component = <Client3DHelloWorldComponent data={client3DData.data} />
+
+  return (
+    component
+  );
+}
+```
+
+In order to use Client 3D, you don't have to modify your Relay Resolvers or schema at all.
+
+Just modify your component in the following ways:
+1. Declare separate fragments for each concrete type implementing `IClient3D` that you're fetching. So in this example, these separate fragments are `FOO_FRAGMENT`, `BAR_FRAGMENT`, and `HELLO_WORLD_FRAGMENT`.
+2. Add the `@module` directive to your fragment, and include the name of the corresponding UI component to this fragment's data as an argument.
+3. Return the final component using Relay's `MatchContainer`, providing the returned query data as a prop.
+
+Notice that in Client 3D, just as in Server 3D, you cannot use `@module` on multiple fragments on the SAME concrete type (but they can be on the same abstract type i.e. a union or an interface).
+
+So in this example, `Client3DFooComponent_Fragment` is on the concrete type `Client3DFoo`, and `Client3DBarComponent_Fragment` is on the concrete type `Client3DBar`. If `Client3DBarComponent_Fragment` was also on `Client3DFoo`, the relay compiler would report an error. However, all three concrete types implement the same parent interface `IClient3D`, which is fine.
+
+<FbInternalOnly>
+
+:::tip
+If you are in www, but not in Comet, you should use `RelayFBMatchContainer` instead of `MatchContainer`.
+:::
+
+</FbInternalOnly>
+
+After Client 3D, your component code will look something like this:
+```jsx
+const {graphql, useFragment, useClientQuery, MatchContainer} = require('react-relay');
+
+component Client3DRelayRenderer() {
+  const FOO_FRAGMENT = graphql`
+    fragment Client3DFooComponent_Fragment on Client3DFoo {
+      data {
+        type
+        info
+      }
+    }
+  `;
+  const BAR_FRAGMENT = graphql`
+    fragment Client3DBarComponent_Fragment on Client3DBar {
+      data {
+        type
+        info
+      }
+    }
+  `;
+  const HELLO_WORLD_FRAGMENT = graphql`
+    fragment Client3DHelloWorldComponent_Fragment on Client3DHelloWorld {
+      data {
+        type
+        info
+      }
+    }
+  `;
+  const client3DData = useClientQuery(
+    graphql`
+      query Client3DRelayQuery {
+        client3D {
+          ...Client3DFooComponent_Fragment
+            @module(name: "Client3DFooComponent.react")
+          ...Client3DBarComponent_Fragment
+            @module(name: "Client3DBarComponent.react")
+          ...Client3DHelloWorldComponent_Fragment
+            @module(name: "Client3DHelloWorldComponent.react")
+        }
+      }
+    `
+  );
+  return (
+    <MatchContainer match={client3DData.client3D} />
+  );
+}
+```
+
+## Limitations
+
+While Client 3D can offer many benefits such as a more intuitive developer experience, enhanced maintainability, and faster performance, it also has some limitations that Server 3D does not.
+
+One key difference is the number of round trips required to fetch data. Server 3D requires at most two round trips: one to the server for data and one to the CDN for JavaScript. In contrast, Client 3D evaluates resolver code as part of rendering the component, which means that the client needs to render the component to discover what JavaScript code is needed. This can lead to additional round trips, especially when dealing with nested Client 3D usage.
+
+For example, consider a blog entry that uses Client 3D to render either a photo blog post or text blog post. The text blog post then uses Client 3D again to determine what type of text presentation format should be used. This can result in nested Client 3D usage, leading to multiple round trips.
+
+Relay is working on solutions to this drawback at the moment, but they have not been productionized yet. Hence, when using Client 3D please make sure that you're not using it in a nested manner to avoid performance degradation.

package/llm-docs/guides/data-driven-dependencies/configuration.mdx

@@ -0,0 +1,127 @@
+---
+id: configuration
+title: Configuration
+slug: /guides/data-driven-dependencies/configuration/
+description: Data driven dependencies configuration
+keywords:
+- 3D
+- 3D config
+- data driven dependencies
+- module
+- match
+- MatchContainer
+---
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+import DocsRating from '@site/src/core/DocsRating';
+
+Server 3D is automatically enabled without any changes to your configuration.
+
+In order to use Client 3D, you need to add an extra field to your relay [compiler configuration](https://relay.dev/docs/getting-started/installation-and-setup/#compiler-configuration) file: `moduleImportConfig`.
+
+<FbInternalOnly>
+
+If you're working on a project in xplat, [config.xplat.json](https://www.internalfb.com/code/fbsource/[3b58a2b59826]/xplat/relay/compiler-rs/config.xplat.json) is your configuration file. If you're working on a
+project in www, [config.www.json](https://www.internalfb.com/code/www/[93b4b956668f]/scripts/relay/compiler-rs/config.www.json) is your configuration file.
+
+</FbInternalOnly>
+
+
+There are 2 subfields in `moduleImportConfig`:
+- `dynamicModuleProvider`: This field defines the way the 3D components will be imported.
+- `surface`: This field defines the surfaces for which client 3D should be enabled.
+
+These fields are necessary to differentiate between different use cases in Meta's internal codebase, but in OSS they're more straightforward.
+
+<FbInternalOnly>
+
+### `dynamicModuleProvider`
+
+`dynamicModuleProvider` has 2 subfields: `mode` and `statement`.
+
+There are 2 modes that `dynamicModuleProvider` can be set to:
+- `JSResource`: This indicates to the Relay Compiler that the 3D component should be imported as a [JSResource](https://www.internalfb.com/intern/wiki/Static_Resources/haste_comet/JSResource/), a dynamically loadable Javascript module. In this case, you can omit the `statement` subfield entirely.
+
+For example:
+
+```js
+"moduleImportConfig": {
+    "dynamicModuleProvider": {
+        "mode": "JSResource"
+    }
+},
+```
+
+- `Custom`: This indicates that you want to write a custom statement import statement to load your 3D component. Fill in the `statement`
+subfield with your custom import statement, using `<$module>` in place of your 3D component name.
+
+For example:
+```js
+"moduleImportConfig": {
+    "dynamicModuleProvider": {
+        "mode": "Custom",
+        "statement": "function() { var JSResource = require('JSResource'); return JSResource('m#<$module>'); }"
+    }
+}
+```
+
+### `surface`
+
+Surface can be set to one of 3 options:
+- `resolvers`: this indicates that Client 3D should work only for data fields determined entirely by Relay Resolvers on the client side. You can consider this to be the "vanilla" client 3D use case.
+
+For example:
+```js
+"moduleImportConfig": {
+    "dynamicModuleProvider": {
+        "mode": "JSResource",
+    },
+    "surface": "resolvers"
+}
+```
+
+- None: you can omit the `surface` configuration field altogether. This is what most projects in Xplat are configured to currently, as
+you can see in the [Xplat relay configuration file](https://www.internalfb.com/code/fbsource/[3b58a2b59826]/xplat/relay/compiler-rs/config.xplat.json). This case is a special variation of Server 3D where the 3D component module information is stored on the client side by the Relay compiler, and not downloaded from the server along with the data at runtime. This variation of Client 3D doesn't offer any performance gains over server 3D. Rather, it was developed for Xplat to support code sharing between Xplat and WWW.
+
+The two config examples given in the `dynamicModuleProvider` section above are both examples of this None case.
+- `all`: this indicates that BOTH the `resolvers` case and None case above should work.
+
+For example:
+```js
+"moduleImportConfig": {
+    "dynamicModuleProvider": {
+        "mode": "JSResource",
+    },
+    "surface": "all"
+}
+```
+
+</FbInternalOnly>
+
+<OssOnly>
+
+### `dynamicModuleProvider`
+
+The `dynamicModuleProvider` has two subfields:
+- `mode`: This should be set to "Custom".
+- `statement`: This is the statement that will be used to import your UI module `<$module>` into the
+parent component where 3D is being used. You can set it to whatever you need to import your module successfully.
+
+### `surface`
+
+The `surface` field should be set to `resolvers`.
+
+Here is an example of what a Relay compiler configuration that enables client 3D could look like:
+
+```js
+"moduleImportConfig": {
+    "dynamicModuleProvider": {
+        "mode": "Custom",
+        "statement": "() => require('./<$module>')"
+    },
+    "surface": "resolvers"
+}
+```
+
+</OssOnly>
+
+<DocsRating />

package/llm-docs/guides/data-driven-dependencies/introduction.mdx

@@ -0,0 +1,39 @@
+---
+id: introduction
+title: Introduction
+slug: /guides/data-driven-dependencies/introduction/
+description: Introduction to data driven dependencies (3D) in Relay
+keywords:
+- 3D
+- data driven dependencies
+- module
+- match
+- MatchContainer
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+Data Driven Dependencies (3D) is a feature in Relay that allows for the dynamic loading of components based on the data being rendered. This is useful when you have multiple possible components that could be used to render a piece of data, and you want to only load the component that is actually needed.
+
+The main benefit of using 3D is that it allows you to avoid loading unnecessary code, which can improve the performance of your application. By only loading the code for the components that are actually needed, you can reduce the overall size of your JavaScript bundle and make your application faster.
+
+In addition to improving performance, 3D also makes it easier to manage complex rendering logic. By allowing you to define multiple possible components for a single piece of data, 3D makes it easy to handle different rendering scenarios without having to write complex conditional logic.
+
+## Use-Cases
+
+There are a few canonical use-cases where 3D is recommended:
+
+* **Fields that are typically null.** For example, a `Comment` type that may optionally include an image. Most comments won't include this type so ideally the code for the image rendering component would only be downloaded when necessary to make the average case faster.
+* **Unions.** For example, a News Feed type may have a union of variants, each rendered by a different React component (e.g. text update, videos, photos, etc.). A given page of stories will only contain a small number of story types, so ideally the application would only have to download the code for the types a user actually sees, rather than all possible story types.
+* **Rendering strategies.** Finally, some pieces of content can be rendered using a variety of different **rendering strategies**. As an example, consider a `Video` type that can be rendered as a thumbnail or autoplaying video, depending on whether the user has opted into autoplaying video. Data-driven dependencies allows products to only download the code and data for the *selected* rendering strategy for each item.
+
+## Types of 3D
+
+There are two types of 3D that Relay supports:
+- [Server 3D](./server-3d.mdx): used when all the data in your 3D-rendered components are resolved on GraphQL servers.
+- [Client 3D](./client-3d.mdx): used when all the data in your 3D-rendered components are resolved via client-side [Relay resolvers](../relay-resolvers/introduction.mdx).
+
+For details on how to configure Relay to support the type of 3D you need, see [Configuration](./configuration.mdx).
+
+<DocsRating />