relay-runtime 20.1.0 → 21.0.0

package/llm-docs/guided-tour/rendering/variables.mdx

@@ -0,0 +1,233 @@
+---
+id: variables
+title: Variables
+slug: /guided-tour/rendering/variables/
+description: Relay guide to query variables
+keywords:
+- query
+- variables
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+You may have noticed that the query declarations in our examples above contain references to an `$id` symbol inside the GraphQL code: these are [GraphQL Variables](https://graphql.org/learn/queries/#variables).
+
+GraphQL variables are a construct that allows referencing dynamic values inside a GraphQL query. When fetching a query from the server, we also need to provide as input the actual set of values to use for the variables declared inside the query:
+
+```graphql
+query UserQuery($id: ID!) {
+  # The value of $id is used as input to the user() call:
+  user(id: $id) {
+    id
+    name
+  }
+}
+```
+
+In the above, `ID!` is the type of the `$id` variable. That is, it is a required ID.
+
+When sending a network request to fetch the query above, we need to provide both the query, and the variables to be used for this particular execution of the query.  For example:
+
+```graphql
+# Query:
+query UserQuery($id: ID!) {
+  # ...
+}
+
+# Variables:
+{"id": 4}
+```
+
+
+<FbInternalOnly>
+
+Fetching the above query and variables from the server would produce the following response, which can also be visualized in [GraphiQL](https://fburl.com/graphiql/kiuar058):
+
+</FbInternalOnly>
+
+<OssOnly>
+
+Fetching the above query and variables from the server would produce the following response:
+
+</OssOnly>
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "4",
+      "name": "Mark Zuckerberg"
+    }
+  }
+}
+```
+
+
+* * *
+
+Fragments can also reference variables that have been declared by a query:
+
+```graphql
+fragment UserFragment on User {
+  name
+  profile_picture(scale: $scale) {
+    uri
+  }
+}
+
+
+query ViewerQuery($scale: Float!) {
+  viewer {
+    actor {
+      ...UserFragment
+    }
+  }
+}
+```
+
+* Even though the fragment above doesn't *declare* the `$scale` variable directly, it can still reference it. Doing so makes it so any query that includes this fragment, either directly or transitively, *must* declare the variable and its type, otherwise an error will be produced.
+* In other words, *query variables are available globally by any fragment that is a descendant of the query*.
+* A fragment which references a global variable can only be included (directly or transitively) in a query which defines that global variable.
+
+
+In Relay, fragment declarations inside components can also reference query variables:
+
+```js
+function UserComponent(props: Props) {
+  const data = useFragment(
+    graphql`
+    fragment UserComponent_user on User {
+      name
+      profile_picture(scale: $scale) {
+        uri
+      }
+    }
+    `,
+    props.user,
+  );
+
+  return (...);
+}
+```
+
+* The above fragment could be included by multiple queries, and rendered by different components, which means that any query that ends up rendering/including the above fragment *must* declare the `$scale` variable.
+*  If any query that happens to include this fragment *doesn't* declare the `$scale` variable, an error will be produced by the Relay Compiler at build time, ensuring that an incorrect query never gets sent to the server (sending a query with missing variable declarations will also produce an error in the server).
+
+
+
+## @arguments and @argumentDefinitions
+
+Relay also provides a way to declare variables that are scoped locally to a fragment using the `@arguments` and `@argumentDefinitions` directives. Fragments that use local variables are easy to customize and reuse, since they do not depend on the value of global (query-level) variables.
+
+```js
+/**
+ * Declare a fragment that accepts arguments with @argumentDefinitions
+ */
+
+function TaskView(props) {
+  const data = useFragment(
+    graphql`
+      fragment TaskView_task on Task
+        @argumentDefinitions(showDetailedResults: {type: "Boolean!"}) {
+        name
+        is_completed
+        ... @include(if: $showDetailedResults) {
+          description
+        }
+      }
+    `,
+    props.task,
+  );
+}
+```
+
+```js
+/**
+ * Include fragment using @arguments
+ */
+
+function TaskList(props) {
+  const data = usePreloadedQuery(
+    graphql`
+      query TaskListQuery {
+        todays_tasks {
+          ...TaskView_task @arguments(showDetailedResults: true)
+        }
+        tomorrows_tasks {
+          ...TaskView_task @arguments(showDetailedResults: false)
+        }
+      }
+    `,
+    props.queryRef,
+  );
+}
+```
+
+* Locally-scoped variables also make it easier to reuse a fragment from another query.
+  * A query definition must list all variables that are used by any nested fragments, including in recursively-nested fragments.
+  * Since a fragment can potentially be accessible from many queries, modifying a fragment that uses global variables can require changes to many query definitions.
+  * This can also lead to awkward situations, like having multiple versions of the "same" variable, such as `$showDetailedResults` and `$showDetails`.
+
+  * Since fragments with only locally-scoped variables do not use global variables, they do not suffer from this issue.
+
+* Note that when passing `@arguments` to a fragment, we can pass a literal value or pass another variable. The variable can be a global query variable, a local variable declared via `@argumentDefinitions` or a literal (e.g. `42.0`).
+* When we actually fetch `TaskView_task` as part of a query, the `showDetailedResults` value will depend on the argument that was provided by the parent of `TaskView_task`:
+
+Fragments that expect arguments can also declare default values, making the arguments optional:
+
+```js
+/**
+ * Declare a fragment that accepts arguments with default values
+ */
+
+function TaskView(props) {
+  const data = useFragment(
+    graphql`
+      fragment TaskView_task on Task
+        @argumentDefinitions(showDetailedResults: {type: "Boolean!", defaultValue: true}) {
+        name
+        is_completed
+        ... @include(if: $showDetailedResults) {
+          description
+        }
+      }
+    `,
+    props.task,
+  );
+}
+```
+
+```js
+function TaskList(props) {
+  const data = usePreloadedQuery(
+    graphql`
+      query TaskListQuery {
+        todays_tasks {
+          ...TaskView_task
+        }
+        tomorrows_tasks {
+          ...TaskView_task @arguments(showDetailedResults: false)
+        }
+      }
+    `,
+    props.queryRef,
+  );
+}
+```
+
+* Not passing the argument to `TaskView_task` makes it use the default value for its locally declared `$showDetailedResult` variable.
+
+
+
+## Accessing GraphQL Variables At Runtime
+
+
+If you want to access the variables that were set at the query root, the recommended approach is to pass the variables down the component tree in your application, using props, or your own application-specific context.
+
+Relay currently does not expose the resolved variables (i.e. after applying argument definitions) for a specific fragment, and you should very rarely need to do so.
+
+
+
+
+<DocsRating />

package/llm-docs/guided-tour/reusing-cached-data/fetch-policies.mdx

@@ -0,0 +1,56 @@
+---
+id: fetch-policies
+title: Fetch Policies
+slug: /guided-tour/reusing-cached-data/fetch-policies/
+description: Relay guide to fetch policies
+keywords:
+- fetch policy
+- network-only
+- store-only
+- store-and-network
+- store-or-network
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+The first step to reusing locally cached data is to pass a `fetchPolicy` to the `loadQuery` function, which can be provided by `useQueryLoader` (see the [Fetching Queries section](../../rendering/queries/)):
+
+```js
+const React = require('React');
+const {graphql} = require('react-relay');
+
+function AppTabs() {
+  const [
+    queryRef,
+    loadQuery,
+  ] = useQueryLoader(HomeTabQuery);
+
+  const onSelectHomeTab = () => {
+    loadQuery({id: '4'}, {fetchPolicy: 'store-or-network'});
+  }
+
+  // ...
+}
+```
+
+The provided `fetchPolicy` will determine:
+
+* *whether* the query should be fulfilled from the local cache, and
+* *whether* a network request should be made to fetch the query from the server, depending on the availability of the data for that query in the store.
+
+
+By default, Relay will try to read the query from the local cache; if any piece of data for that query is [missing](../presence-of-data/) or [stale](../staleness-of-data/), it will fetch the entire query from the network. This default `fetchPolicy` is called "*store-or-network".*
+
+Specifically, `fetchPolicy` can be any of the following options: **
+
+* "store-or-network": *(default)* *will* reuse locally cached data, and will *only* send a network request if any data for the query is [missing](../presence-of-data/) or [stale](../staleness-of-data/). If the query is fully cached, a network request will *not* be made.
+* "store-and-network": *will* reuse locally cached data and will *always* send a network request, regardless of whether any data was [missing](../presence-of-data/) or [stale](../staleness-of-data/) in the store.
+* "network-only": *will* *not* reuse locally cached data, and will *always* send a network request to fetch the query, ignoring any data that might be locally cached and whether it's [missing](../presence-of-data/) or [stale](../staleness-of-data/).
+* "store-only": *will* *only* reuse locally cached data, and will *never* send a network request to fetch the query. In this case, the responsibility of fetching the query falls to the caller, but this policy could also be used to read and operate on data that is entirely [local](../../updating-data/local-data-updates/).
+
+
+Note that the `refetch` function discussed in the [Refetching Queries](../refetching/refetching-queries-with-different-data.mdx) section also takes a `fetchPolicy`.
+
+
+<DocsRating />

package/llm-docs/guided-tour/reusing-cached-data/filling-in-missing-data.mdx

@@ -0,0 +1,102 @@
+---
+id: filling-in-missing-data
+title: Filling in Missing Data (Missing Field Handlers)
+slug: /guided-tour/reusing-cached-data/filling-in-missing-data/
+description: Relay guide to filling in missing data
+keywords:
+- missing field handler
+- missing data
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+// @fb-only
+
+In the previous section we covered how to reuse data that is fully or partially cached, however there are cases in which Relay can't automatically tell that it can reuse some of the data it already has from other queries in order to fulfill a specific query. Specifically, Relay knows how to reuse data that is cached for a query that has been fetched before; that is, if you fetch the exact same query twice, Relay will know that it has the data cached for that query the second time it tries to evaluate it.
+
+However, when using different queries, there might still be cases where different queries point to the same data, which we'd want to be able to reuse. For example, imagine the following two queries:
+
+```js
+// Query 1
+
+query UserQuery {
+  user(id: 4) {
+    name
+  }
+}
+```
+
+```js
+// Query 2
+
+query NodeQuery {
+  node(id: 4) {
+    ... on User {
+      name
+    }
+  }
+}
+```
+
+
+These two queries are different, but reference the exact same data. Ideally, if one of the queries was already cached in the store, we should be able to reuse that data when rendering the other query. However, Relay doesn't have this knowledge by default, so we need to configure it to encode the knowledge that a `node(id: 4)` *"is the same as"* `user(id: 4)`.
+
+To do so, we can provide `missingFieldHandlers` to the `RelayEnvironment` which specifies this knowledge.
+
+// @fb-only
+
+```js
+const {ROOT_TYPE, Environment} = require('relay-runtime');
+
+const missingFieldHandlers = [
+  {
+    handle(field, record, argValues): ?string {
+      // Make sure to add a handler for the node field
+      if (
+        record != null &&
+        record.getType() === ROOT_TYPE &&
+        field.name === 'node' &&
+        argValues.hasOwnProperty('id')
+      ) {
+        return argValues.id
+      }
+      if (
+        record != null &&
+        record.getType() === ROOT_TYPE &&
+        field.name === 'user' &&
+        argValues.hasOwnProperty('id')
+      ) {
+        // If field is user(id: $id), look up the record by the value of $id
+        return argValues.id;
+      }
+      if (
+        record != null &&
+        record.getType() === ROOT_TYPE &&
+        field.name === 'story' &&
+        argValues.hasOwnProperty('story_id')
+      ) {
+        // If field is story(story_id: $story_id), look up the record by the
+        // value of $story_id.
+        return argValues.story_id;
+      }
+      return undefined;
+    },
+    kind: 'linked',
+  },
+];
+
+const environment = new Environment({/*...*/, missingFieldHandlers});
+```
+
+* `missingFieldHandlers` is an array of *handlers*. Each handler must specify a `handle` function, and the kind of missing fields it knows how to handle. The 2 main types of fields that you'd want to handle are:
+    * *'scalar'*: This represents a field that contains a scalar value, for example a number or a string.
+    * *'linked'*: This represents a field that references another object, i.e. not a scalar.
+* The `handle` function takes the field that is missing, the record that field belongs to, and any arguments that were passed to the field in the current execution of the query.
+    * When handling a *'scalar'* field, the handle function should return a scalar value, in order to use as the value for a missing field
+    * When handling a *'linked'* field*,* the handle function should return an *ID*, referencing another object in the store that should be use in place of the missing field. **
+* As Relay attempts to fulfill a query from the local cache, whenever it detects any missing data, it will run any of the provided missing field handlers that match the field type before definitively declaring that the data is missing.
+
+
+
+<DocsRating />

package/llm-docs/guided-tour/reusing-cached-data/introduction.mdx

@@ -0,0 +1,22 @@
+---
+id: introduction
+title: Reusing Cached Data
+slug: /guided-tour/reusing-cached-data/
+description: Relay guide to reusing cached data
+keywords:
+- reusing
+- cached
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+While an app is in use, Relay will accumulate and cache *(for some time)* the data for the multiple queries that have been fetched throughout usage of our app. Often times, we'll want to be able to reuse and immediately render this data that is locally cached instead of waiting for a network request when fulfilling a query; this is what we'll cover in this section.
+
+Some examples of when this might be useful are:
+
+* Navigating between tabs in an app, where each app renders a query. If a tab has already been visited, re-visiting the tab should render it instantly, without having to wait for a network request to fetch the data that we've already fetched before.
+* Navigating to a post that was previously rendered on a feed. If the post has already been rendered on a feed, navigating to the post's permalink page should render the post immediately, since all of the data for the post should already be cached.
+    * Even if rendering the post in the permalink page requires more data than rendering the post on a feed, we'd still like to reuse and immediately render as much of the post's data that we already have available locally, without blocking render for the entire post if only a small bit of data is missing.
+
+<DocsRating />

package/llm-docs/guided-tour/reusing-cached-data/presence-of-data.mdx

@@ -0,0 +1,93 @@
+---
+id: presence-of-data
+title: Presence of Data
+slug: /guided-tour/reusing-cached-data/presence-of-data/
+description: Relay guide to the presence of data
+keywords:
+- presence
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+// @fb-only
+
+
+An important thing to keep in mind when attempting to reuse data that is cached in the Relay store is to understand the lifetime of that data; that is, if it is present in the store, and for how long it will be.
+
+Data in the Relay store for a given query will generally be present after the query has been fetched for the first time, as long as that query is being rendered on the screen. If we've never fetched data for a specific query, then it will be missing from the store.
+
+However, even after we've fetched data for different queries, we can't keep all of the data that we've fetched indefinitely in memory, since over time it would grow to be too large and too stale. In order to mitigate this, Relay runs a process called *Garbage Collection*, in order to delete data that we're no longer using.
+
+## Garbage Collection in Relay
+
+Specifically, Relay runs garbage collection on the local in-memory store by deleting any data that is no longer being referenced by any component in the app.
+
+However, this can be at odds with reusing cached data; if the data is deleted too soon, before we try to reuse it again later, that will prevent us from reusing that data to render a screen without having to wait on a network request. To address this, this section will cover what you need to do in order to ensure that the data you want to reuse is kept cached for as long as you need it.
+
+
+:::note
+NOTE: Usually, you shouldn't need to worry about configuring garbage collection and data retention, as this should be configured by the app infrastructure at the RelayEnvironment level; however, we will cover it here for reference.
+:::
+
+// @fb-only
+
+
+
+## Query Retention
+
+Retaining a query indicates to Relay that the data for that query and variables shouldn't be deleted (i.e. garbage collected). Multiple callers might retain a single query, and as long as there is at least one caller retaining a query, it won't be deleted from the store.
+
+By default, any query components using `useQueryLoader` / `usePreloadedQuery` or our other APIs will retain the query for as long as they are mounted. After they unmount, they will release the query, which means that the query might be deleted at any point in the future after that occurs.
+
+If you need to retain a specific query outside of the components lifecycle, you can use the [`retain`](../../accessing-data-without-react/retaining-queries/) operation:
+
+```js
+// Retain query; this will prevent the data for this query and
+// variables from being garbage collected by Relay
+const disposable = environment.retain(queryDescriptor);
+
+// Disposing of the disposable will release the data for this query
+// and variables, meaning that it can be deleted at any moment
+// by Relay's garbage collection if it hasn't been retained elsewhere
+disposable.dispose();
+```
+
+* As mentioned, this will allow you to retain the query even after a query component has unmounted, allowing other components, or future instances of the same component, to reuse the retained data.
+
+
+## Controlling Relay's Garbage Collection Policy
+
+There are currently 2 options you can provide to your Relay Store in to control the behavior of garbage collection:
+
+### GC Scheduler
+
+The `gcScheduler` is a function you can provide to the Relay Store which will determine when a GC execution should be scheduled to run:
+
+```js
+// Sample scheduler function
+// Accepts a callback and schedules it to run at some future time.
+function gcScheduler(run: () => void) {
+  resolveImmediate(run);
+}
+
+const store = new Store(source, {gcScheduler});
+```
+
+* By default, if a `gcScheduler` option is not provided, Relay will schedule garbage collection using the `resolveImmediate` function.
+* You can provide a scheduler function to make GC scheduling less aggressive than the default, for example based on time or [scheduler](https://github.com/facebook/react/tree/main/packages/scheduler) priorities, or any other heuristic. By convention, implementations should not execute the callback immediately.
+
+
+### GC Release Buffer Size
+
+The Relay Store internally holds a release buffer to keep a specific (configurable) number of queries temporarily retained even *after* they have been released by their original owner  (which will happen by default when a component rendering that query unmounts). This makes it possible (and more likely) to be able to reuse data when navigating back to a page, tab or piece of content that has been visited before.
+
+In order to configure the size of the release buffer, we can specify the `gcReleaseBufferSize` option to the Relay Store:
+
+```js
+const store = new Store(source, {gcReleaseBufferSize: 10});
+```
+
+* Note that having a buffer size of 0 is equivalent to not having the release buffer, which means that queries will be immediately released and collected.
+* By default, environments have a release buffer size of 10.
+
+<DocsRating />

package/llm-docs/guided-tour/reusing-cached-data/rendering-partially-cached-data.mdx

@@ -0,0 +1,175 @@
+---
+id: rendering-partially-cached-data
+title: Rendering Partially Cached Data
+slug: /guided-tour/reusing-cached-data/rendering-partially-cached-data/
+description: Relay guide to rendering partially cached data
+keywords:
+- partially cached data
+- renderPolicy
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+// @fb-only
+// @fb-only
+
+When rendering cached data in Relay, it is possible to perform partial rendering. We define *"partial rendering"* as the ability to immediately render a query that is partially cached. That is, parts of the query might be missing, but parts of the query might already be cached. In these cases, we want to be able to immediately render the parts of the query that are cached, without waiting on the full query to be fetched.
+
+This can be useful in scenarios where we want to render a screen or a page as fast as possible, and we know that some of the data for that page is already cached so we can skip a loading state. For example, take the profile page: it is very likely that the user's name has already been cached at some point during usage of the app, so when visiting a profile page, if the name of the user is cached, we'd like to render immediately, even if the rest of the data for the profile page isn't available yet.
+
+
+### Fragments as boundaries for partial rendering
+
+To do this, we rely on the ability of fragment components to *suspend* (see the [Loading States with Suspense](../../rendering/loading-states/) section). A fragment component will suspend if any of the data it declared locally is missing during render, and is currently being fetched. Specifically, it will suspend until the data it requires is fetched, that is, until the query to which it belongs (its *parent query*) is fetched.
+
+Let's explain what this means with an example. Say we have the following fragment component:
+
+```js
+/**
+ * UsernameComponent.react.js
+ *
+ * Fragment Component
+ */
+
+import type {UsernameComponent_user$key} from 'UsernameComponent_user.graphql';
+
+const React = require('React');
+const {graphql, useFragment} = require('react-relay');
+
+type Props = {
+  user: UsernameComponent_user$key,
+};
+
+function UsernameComponent(props: Props) {
+  const user = useFragment(
+    graphql`
+      fragment UsernameComponent_user on User {
+        username
+      }
+    `,
+    props.user,
+  );
+  return (...);
+}
+
+module.exports = UsernameComponent;
+```
+
+
+And we have the following query component,  which queries for some data, and also includes the fragment above:
+
+```javascript
+/**
+ * AppTabs.react.js
+ *
+ * Query Loader Component
+ */
+
+ // ....
+
+  const onSelectHomeTab = () => {
+    loadHomeTabQuery({id: '4'}, {fetchPolicy: 'store-or-network'});
+  }
+
+ // ...
+
+/**
+ * HomeTab.react.js
+ *
+ * Query Component
+ */
+
+const React = require('React');
+const {graphql, usePreloadedQuery} = require('react-relay');
+
+const UsernameComponent = require('./UsernameComponent.react');
+
+function HomeTab(props: Props) {
+  const data = usePreloadedQuery(
+    graphql`
+      query HomeTabQuery($id: ID!) {
+        user(id: $id) {
+          name
+          ...UsernameComponent_user
+        }
+      }
+    `,
+    props.queryRef,
+  );
+
+  return (
+    <>
+      <h1>{data.user?.name}</h1>
+      <UsernameComponent user={data.user} />
+    </>
+  );
+}
+```
+
+
+Say that when this `HomeTab` component is rendered, we've already previously fetched *(_only_)* the `name` for the `User` with `{id: 4}`, and it is locally cached in the Relay store associated with our current Relay environment.
+
+If we attempt to render the query with a `fetchPolicy` that allows reusing locally cached data (`'store-or-network'`, or `'store-and-network'`), the following will occur:
+
+* The query will check if any of its locally-required data is missing. In this case, *it isn't*. Specifically, the query is only directly selecting the `name` field, and that field *is* available in the store.
+  * Relay considers data to be missing only if it is declared locally and missing. In other words, data that is selected within fragment spreads does not affect whether the outer query or fragment is determined to have missing data.
+* Given that the query doesn't have any data missing, it will render, and then attempt to render the child `UsernameComponent`.
+* When the `UsernameComponent` attempts to render the `UsernameComponent_user` fragment, Relay will notice that some of the data required to render is missing; specifically, the `username` is missing. At this point, since `UsernameComponent` has missing data, it will suspend rendering until the network request completes. Note that regardless of which `fetchPolicy` you choose, a network request will always be started if any piece of data for the full query, i.e. including fragments, is missing.
+
+
+At this point, when `UsernameComponent` suspends due to the missing `username`, ideally we should still be able to render the `User`'s `name` immediately, since it's locally cached. However, since we aren't using a `Suspense` component to catch the fragment's suspension, the suspension will bubble up and the entire `App` component will be suspended.
+
+In order to achieve the desired effect of rendering the `name` when it's available even if the `username`  is missing, we just need to wrap the `UsernameComponent` in `Suspense,` to *allow* the other parts of `App` to continue rendering:
+
+```js
+/**
+ * HomeTab.react.js
+ *
+ * Query Component
+ */
+
+const React = require('React');
+const {Suspense} = require('React');
+const {graphql, usePreloadedQuery} = require('react-relay');
+
+const UsernameComponent = require('./UsernameComponent.react');
+
+
+function HomeTab() {
+  const data = usePreloadedQuery(
+    graphql`
+      query AppQuery($id: ID!) {
+        user(id: $id) {
+          name
+          ...UsernameComponent_user
+        }
+      }
+    `,
+    props.queryRef,
+  );
+
+  return (
+    <>
+      <h1>{data.user?.name}</h1>
+
+      {/*
+        Wrap the UserComponent in Suspense to allow other parts of the
+        App to be rendered even if the username is missing.
+      */}
+      <Suspense fallback={<LoadingSpinner label="Fetching username" />}>
+        <UsernameComponent user={data.user} />
+      </Suspense>
+    </>
+  );
+}
+```
+
+// @fb-only
+
+The process that we described above works the same way for nested fragments (i.e. fragments included within other fragments). This means that if the data required to render a fragment is locally cached, the fragment component will be able to render, regardless of whether data for any of its child or descendant fragments is missing. If data for a child fragment is missing, we can wrap it in a `Suspense` component to allow other fragments and parts of the app to continue rendering.
+
+As mentioned in our motivating example, this is desirable because it can allows us to skip loading states entirely. More specifically, the ability to render data that is partially available allows us to render intermediate UI states that more closely resemble the final rendered state.
+
+// @fb-only
+
+<DocsRating />