relay-runtime 20.1.0 → 21.0.0

package/llm-docs/guided-tour/rendering/loading-states.mdx

@@ -0,0 +1,245 @@
+---
+id: loading-states
+title: Loading States with Suspense
+slug: /guided-tour/rendering/loading-states/
+description: Relay guide to loading states
+keywords:
+- suspense
+- loading
+- glimmer
+- fallback
+- spinner
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+// @fb-only
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+// @fb-only
+// @fb-only
+// @fb-only
+// @fb-only
+// @fb-only
+
+
+As you may have noticed, we mentioned that using `usePreloadedQuery` and `useLazyLoadQuery` will render data from a query that was being fetched from the server, but we didn't elaborate on how to render a loading UI (such as a glimmer) while that data is still being fetched. We will cover that in this section.
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+<OssOnly>
+
+To render loading states while a query is being fetched, we rely on [React Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html). Suspense is a new feature in React that allows components to interrupt or *"suspend"* rendering in order to wait for some asynchronous resource (such as code, images or data) to be loaded; when a component "suspends", it indicates to React that the component isn't *"ready"* to be rendered yet, and won't be until the asynchronous resource it's waiting for is loaded. When the resource finally loads, React will try to render the component again.
+
+</OssOnly>
+
+This capability is useful for components to express asynchronous dependencies like data, code, or images that they require in order to render, and lets React coordinate rendering the loading states across a component tree as these asynchronous resources become available. More generally, the use of Suspense give us better control to implement more deliberately designed loading states when our app is loading for the first time or when it's transitioning to different states, and helps prevent accidental flickering of loading elements (such as spinners), which can commonly occur when loading sequences aren't explicitly designed and coordinated.
+
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+## Loading fallbacks with Suspense Boundaries
+
+When a component is suspended, we need to render a *fallback* in place of the component while we wait for it to become *"ready"*. In order to do so, we use the `Suspense` component provided by React:
+
+```js
+const React = require('React');
+const {Suspense} = require('React');
+
+function App() {
+  return (
+    // Render a fallback using Suspense as a wrapper
+    <Suspense fallback={<LoadingGlimmer />}>
+      <CanSuspend />
+    </Suspense>
+  );
+}
+```
+
+
+`Suspense` components can be used to wrap any component; if the target component suspends, `Suspense` will render the provided fallback until all its descendants become *"ready"* (i.e. until *all* of the suspended components within the subtree resolve). Usually, the fallback is used to render fallback loading states such as a glimmers and placeholders.
+
+Usually, different pieces of content in our  app might suspend, so we can show loading state until they are resolved by using `Suspense` :
+
+```js
+/**
+ * App.react.js
+ */
+
+const React = require('React');
+const {Suspense} = require('React');
+
+function App() {
+  return (
+    // LoadingGlimmer is rendered via the Suspense fallback
+    <Suspense fallback={<LoadingGlimmer />}>
+      <MainContent /> {/* MainContent may suspend */}
+    </Suspense>
+  );
+}
+```
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+Let's distill what's going on here:
+
+* If `MainContent` suspends because it's waiting on some asynchronous resource (like data), the `Suspense` component that wraps `MainContent` will detect that it suspended, and will render the `fallback` element (i.e. the `LoadingGlimmer` in this case) up until `MainContent` is ready to be rendered. Note that this also transitively includes descendants of `MainContent`, which might also suspend.
+
+
+What's nice about Suspense is that you have granular control about how to accumulate loading states for different parts of your component tree:
+
+```js
+/**
+ * App.react.js
+ */
+
+const React = require('React');
+const {Suspense} = require('React');
+
+function App() {
+  return (
+    // A LoadingGlimmer for all content is rendered via the Suspense fallback
+    <Suspense fallback={<LoadingGlimmer />}>
+      <MainContent />
+      <SecondaryContent /> {/* SecondaryContent can also suspend */}
+    </Suspense>
+  );
+}
+```
+
+// @fb-only
+
+* In this case, both `MainContent` and `SecondaryContent` may suspend while they load their asynchronous resources; by wrapping both in a `Suspense`, we can show a single loading state up until they are *all* ready, and then render the entire content in a single paint, after everything has successfully loaded.
+* In fact, `MainContent` and `SecondaryContent` may suspend for different reasons other than fetching data, but the same `Suspense` component can be used to render a fallback up until *all* components in the subtree are ready to be rendered. Note that this also transitively includes descendants of `MainContent` or `SecondaryContent`, which might also suspend.
+
+
+Conversely, you can also decide to be more granular about your loading UI and wrap Suspense components around smaller or individual parts of your component tree:
+
+```js
+/**
+ * App.react.js
+ */
+
+const React = require('React');
+const {Suspense} = require('React');
+
+function App() {
+  return (
+    <>
+      {/* Show a separate loading UI for the LeftHandColumn */}
+      <Suspense fallback={<LeftColumnPlaceholder />}>
+        <LeftColumn />
+      </Suspense>
+
+      {/* Show a separate loading UI for both the Main and Secondary content */}
+      <Suspense fallback={<LoadingGlimmer />}>
+        <MainContent />
+        <SecondaryContent />
+      </Suspense>
+    </>
+  );
+}
+```
+
+// @fb-only
+
+* In this case, we're showing 2 separate loading UIs:
+    * One to be shown until the `LeftColumn` becomes ready
+    * And one to be shown until both the `MainContent` and `SecondaryContent` become ready.
+* What is powerful about this is that by more granularly wrapping our components in Suspense, *we allow other components to be rendered earlier as they become ready*. In our example, by separately wrapping `MainContent` and `SecondaryContent` under `Suspense`, we're allowing `LeftColumn` to render as soon as it becomes ready, which might be earlier than when the content sections become ready.
+
+
+## Transitions and Updates that Suspend
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+<OssOnly>
+
+`Suspense` boundary fallbacks allow us to describe our loading placeholders when initially rendering some content, but our applications will also have transitions between different content. Specifically, when switching between two components within an already mounted boundary, the new component you're switching to might not have loaded all of its async dependencies, which means that it might also suspend.
+
+In these cases, we would still show the `Suspense` boundary fallbacks. However, this means that we would hide existing content in favor of showing the `Suspense` fallback. In future versions of React when concurrent rendering is supported, React will provide an option to support this case and avoid hiding already rendered content with a Suspense fallback when suspending.
+
+</OssOnly>
+
+## How We Use Suspense in Relay
+
+### Queries
+
+In our case, our query components are components that can suspend, so we use Suspense to render loading states while a query is being fetched. Let's see what that looks like in practice:
+
+Say we have the following query renderer component:
+
+```js
+/**
+ * MainContent.react.js
+ *
+ * Query Component
+ */
+
+const React = require('React');
+const {graphql, usePreloadedQuery} = require('react-relay');
+
+function MainContent(props) {
+  // Fetch and render a query
+  const data = usePreloadedQuery(
+    graphql`...`,
+    props.queryRef,
+  );
+
+  return (...);
+}
+```
+
+```js
+/**
+ * App.react.js
+ */
+
+const React = require('React');
+const {Suspense} = require('React');
+
+function App() {
+  return (
+    // LoadingGlimmer is rendered via the Suspense fallback
+    <Suspense fallback={<LoadingGlimmer />}>
+      <MainContent /> {/* MainContent may suspend */}
+    </Suspense>
+  );
+}
+```
+
+// @fb-only
+
+Let's distill what's going on here:
+
+* We have a `MainContent` component, which is a query renderer that fetches and renders a query. `MainContent` will *suspend* rendering when it attempts to fetch the query, indicating that it isn't ready to be rendered yet, and it will resolve when the query is fetched.
+* The `Suspense `component that wraps `MainContent` will detect that `MainContent` suspended, and will render the `fallback` element (i.e. the `LoadingGlimmer` in this case) up until `MainContent` is ready to be rendered; that is, up until the query is fetched.
+
+
+### Fragments
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+<OssOnly>
+
+Fragments are also integrated with Suspense in order to support rendering of data that's being `@defer'`d or data that's partially available in the Relay Store (i.e. [partial rendering](../../reusing-cached-data/rendering-partially-cached-data/)).
+
+</OssOnly>
+
+### Transitions
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+Additionally, our APIs for fetching, [refreshing](../refetching/refreshing-queries.mdx) and [refetching](../refetching/refetching-queries-with-different-data.mdx) and for [rendering connections](../list-data/connections.mdx) are also integrated with Suspense; for these use cases, these APIs will also suspend.
+
+<DocsRating />

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

@@ -0,0 +1,261 @@
+---
+id: queries
+title: Queries
+slug: /guided-tour/rendering/queries/
+description: Relay guide to queries
+keywords:
+- query
+- usePreloadedQuery
+- useLazyLoadQuery
+- useQueryLoader
+- loadQuery
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+// @fb-only
+
+A [GraphQL Query](https://graphql.org/learn/queries/) is a description of data you want to query from a GraphQL server. It consists of a set of fields (and potentially [fragments](../fragments/)) that we want to request from the GraphQL server. What we can query for will depend on the [GraphQL Schema](https://graphql.org/learn/schema/) exposed on the server, which describes the data that is available for querying.
+
+A query can be sent as a request over the network, along with an optional collection of [variables](../variables/) that the query uses, in order to fetch the data. The server response will be a JSON object that matches the shape of the query we sent:
+
+```graphql
+query UserQuery($id: ID!) {
+  user(id: $id) {
+    id
+    name
+    ...UserFragment
+  }
+  viewer {
+    actor {
+      name
+    }
+  }
+}
+
+fragment UserFragment on User {
+  username
+}
+```
+
+<FbInternalOnly>
+
+[Sample response](https://fburl.com/graphiql/v5hs717f):
+
+</FbInternalOnly>
+
+<OssOnly>
+
+Sample response:
+
+</OssOnly>
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "4",
+      "name": "Mark Zuckerberg",
+      "username": "zuck"
+    },
+    "viewer": {
+      "actor": {
+        "name": "Your Name"
+      }
+    }
+  }
+}
+```
+
+
+
+## Rendering Queries
+
+To *render* a query in Relay, you can use the `usePreloadedQuery` hook. `usePreloadedQuery` takes a query definition and a query reference, and returns the corresponding data for that query and reference.
+
+```js
+import type {HomeTabQuery} from 'HomeTabQuery.graphql';
+import type {PreloadedQuery} from 'react-relay';
+
+const React = require('React');
+const {graphql, usePreloadedQuery} = require('react-relay');
+
+type Props = {
+  queryRef: PreloadedQuery<HomeTabQuery>,
+};
+
+function HomeTab(props: Props) {
+  const data = usePreloadedQuery(
+    graphql`
+      query HomeTabQuery($id: ID!) {
+        user(id: $id) {
+          name
+        }
+      }
+    `,
+    props.queryRef,
+  );
+
+  return (
+    <h1>{data.user?.name}</h1>
+  );
+}
+```
+
+Lets see what's going on here:
+
+* `usePreloadedQuery`  takes a `graphql` query and a `PreloadedQuery` reference, and returns the data that was fetched for that query.
+    * The `PreloadedQuery` (in this case `queryRef`) is an object that describes and references an *instance* of our query that is being (or was) fetched.
+        * We'll cover how to actually fetch the query in the next section below, and cover how to show loading states if the query is in-flight when we try to render it in the [Loading States with Suspense](../loading-states/) section.
+* Similarly to [fragments](../fragments/), *the component is automatically subscribed to updates to the query data*: if the data for this query is updated anywhere in the app, the component will automatically re-render with the latest updated data.
+* `usePreloadedQuery` also takes a Flow type parameter, which corresponds to the Flow type for the query, in this case `HomeTabQuery`.
+    * The Relay compiler automatically generates Flow types for any declared queries, which are available to import from the generated files with the following name format: *`<query_name>`*`.graphql.js`.
+    * Note that the `data` is already properly Flow-typed without requiring an explicit annotation, and is based on the types from the GraphQL schema. For example, the type of `data` above would be: `{ user: ?{ name: ?string } }`.
+* Make sure you're providing a Relay environment using a [Relay Environment Provider](../environment/) at the root of your app before trying to render a query.
+
+
+## Fetching Queries for Render
+
+Apart from *rendering* a query, we also need to fetch it from the server. Usually we want to fetch queries somewhere at the root of our app, and only have **one or a few queries that [*accumulate*](../fragments/#composing-fragments-into-queries) all the data required to render the screen**. Ideally, we'd fetch them as early as possible, before we even start rendering our app.
+
+In order to *fetch* a query for later rendering it, you can use the `useQueryLoader` Hook:
+
+```js
+import type {HomeTabQuery as HomeTabQueryType} from 'HomeTabQuery.graphql';
+import type {PreloadedQuery} from 'react-relay';
+
+const HomeTabQuery = require('HomeTabQuery.graphql')
+const {useQueryLoader} = require('react-relay');
+
+
+type Props = {
+  initialQueryRef: PreloadedQuery<HomeTabQueryType>,
+};
+
+function AppTabs(props) {
+  const [
+    homeTabQueryRef,
+    loadHomeTabQuery,
+  ] = useQueryLoader(
+    HomeTabQuery,
+    props.initialQueryRef, /* e.g. provided by router */
+  );
+
+  const onSelectHomeTab = () => {
+    // Start loading query for HomeTab immediately in the event handler
+    // that triggers navigation to that tab, *before* we even start
+    // rendering the target tab.
+    // Calling this function will update the value of homeTabQueryRef.
+    loadHomeTabQuery({id: '4'});
+
+    // ...
+  }
+
+  // ...
+
+  return (
+    screen === 'HomeTab' && homeTabQueryRef != null ?
+      // Pass to component that uses usePreloadedQuery
+      <HomeTab queryRef={homeTabQueryRef} /> :
+      // ...
+  );
+}
+```
+
+The example above is somewhat contrived, but let's distill what is happening:
+
+* We are calling `useQueryLoader` inside our `AppTabs` component.
+    * It takes a query, which in this case is our `HomeTabQuery` (the query that we declared in our previous example), and which we can obtain by requiring the auto-generated file: `'HomeTabQuery.graphql'`.
+    * It takes an optional initial `PreloadedQuery` to be used as the initial value of the `homeTabQueryRef` that is stored in state and returned by `useQueryLoader`.
+    * It also additionally takes a Flow type parameter, which corresponds to the Flow type for the query, in this case `HomeTabQueryType`, which you can also obtain from the auto-generated file: `'HomeTabQuery.graphql'`.
+* Calling `useQueryLoader` allows us to obtain 2 things:
+    * `homeTabQueryRef`: A `?PreloadedQuery`, which is an object that describes and references an *instance* of our query that is being (or was) fetched. This value will be null if we haven't fetched the query, i.e. if we haven't called `loadHomeTabQuery`.
+    * `loadHomeTabQuery`: A function that will *fetch* the data for this query from the server (if it isn't already cached), and given an object with the [variables](../variables/) the query expects, in this case `{id: '4'}` (we'll go into more detail about how Relay uses cached data in the [Reusing Cached Data For Render](../../reusing-cached-data/) section). Calling this function will also update the value of `homeTabQueryRef` to an instance of a `PreloadedQuery`.
+        * Note that the `variables` we pass to this function will be checked by Flow to ensure that you are passing values that match what the GraphQL query expects.
+        * Also note that we are calling this function in the event handler that causes the `HomeTab` to be rendered. This allows us to start fetching the data for the screen as early as possible, even before the new tab starts rendering.
+            * In fact, `loadQuery` will throw an error if it is called during React's render phase!
+* Note that `useQueryLoader` will automatically dispose of all queries that have been loaded when the component unmounts. Disposing of a query means that Relay will no longer hold on to the data for that particular instance of the query in its cache (we'll cover the lifetime of query data in [Reusing Cached Data For Render](../../reusing-cached-data/) section). Additionally, if the request for the query is still in flight when disposal occurs, it will be canceled.
+* Our `AppTabs` component renders the `HomeTab` component from the previous example, and passes it the corresponding query reference. Note that this parent component owns the lifetime of the data for that query, meaning that when it unmounts, it will of dispose of that query, as mentioned above.
+* Finally, make sure you're providing a Relay environment using a [Relay Environment Provider](../environment/) at the root of your app before trying to use `useQueryLoader`.
+
+
+Sometimes, you want to start a fetch outside of the context of a parent component, for example to fetch the data required for the initial load of the application. For these cases, you can use the `loadQuery` API directly, without using `useQueryLoader`:
+
+```js
+import type {HomeTabQuery as HomeTabQueryType} from 'HomeTabQuery.graphql';
+
+const HomeTabQuery = require('HomeTabQuery.graphql')
+const {loadQuery} = require('react-relay');
+
+
+const environment = createEnvironment(...);
+
+// At some point during app initialization
+const initialQueryRef = loadQuery<HomeTabQueryType>(
+  environment,
+  HomeTabQuery,
+  {id: '4'},
+);
+
+// ...
+
+// E.g. passing the initialQueryRef to the root component
+render(<AppTabs initialQueryRef={initialQueryRef} initialTab={...} />)
+```
+
+* In this example, we are calling the `loadQuery` function directly to obtain a `PreloadedQuery` instance that we can later pass to a component that uses `usePreloadedQuery`.
+* In this case, we would expect the root `AppTabs` component to manage the lifetime of the query reference, and dispose of it at the appropriate time, if at all.
+* We've left the details of "app initialization" vague in this example, since that will vary from application to application. The important thing to note here is that we should obtain a query reference before we start rendering the root component. In fact, `loadQuery` will throw an error if it is called during React's render phase!
+
+
+### Render as you Fetch
+
+The examples above illustrate how to separate fetching the data from rendering it, in order to start the fetch as early as possible (as opposed to waiting until the component is rendered to start the fetch), and allow us to show content to our users a lot sooner. It also helps prevent waterfalling round trips, and gives us more control and predictability over when the fetch occurs, whereas if we fetch during render, it becomes harder to determine when the fetch will (or should) occur. This fits nicely with the [*"render-as-you-fetch"*](https://reactjs.org/docs/concurrent-mode-suspense.html#approach-3-render-as-you-fetch-using-suspense) pattern with [React Suspense](../loading-states/).
+
+This is the preferred pattern for fetching data with Relay, and it applies in several circumstances, such as the initial load of an application, during subsequent navigations, or generally when using UI elements which are initially hidden and later revealed upon an interaction (such as menus, popovers, dialogs, etc), and which also require fetching additional data.
+
+// @fb-only
+
+
+## Lazily Fetching Queries during Render
+
+Another alternative for fetching a query is to lazily fetch the query when the component is rendered. However, as we've mentioned previously, the preferred pattern is to start fetching queries ahead of rendering. If lazy fetching is used without caution, it can trigger nested or waterfalling round trips, and can degrade performance.
+
+To fetch a query lazily, you can use the `useLazyLoadQuery` Hook:
+
+```js
+const React = require('React');
+const {graphql, useLazyLoadQuery} = require('react-relay');
+
+function App() {
+  const data = useLazyLoadQuery(
+    graphql`
+      query AppQuery($id: ID!) {
+        user(id: $id) {
+          name
+        }
+      }
+    `,
+    {id: '4'},
+  );
+
+  return (
+    <h1>{data.user?.name}</h1>
+  );
+}
+```
+Lets see what's going on here:
+
+* `useLazyLoadQuery`  takes a graphql query and some variables for that query, and returns the data that was fetched for that query. The variables are an object containing the values for the [variables](../variables/) referenced inside the GraphQL query.
+* Similarly to [fragments](../fragments/), the component is automatically subscribed to updates to the query data: if the data for this query is updated anywhere in the app, the component will automatically re-render with the latest updated data.
+* `useLazyLoadQuery` additionally takes a Flow type parameter, which corresponds to the Flow type for the query, in this case AppQuery.
+    * Remember that Relay automatically generates Flow types for any declared queries, which you can import and use with `useLazyLoadQuery`. These types are available in the generated files with the following name format: `<query_name>.graphql.js`.
+    * Note that the `variables` will be checked by Flow to ensure that you are passing values that match what the GraphQL query expects.
+    * Note that the data is already properly Flow-typed without requiring an explicit annotation, and is based on the types from the GraphQL schema. For example, the type of `data` above would be: `{ user: ?{ name: ?string } }`.
+* By default, when the component renders, Relay will *fetch* the data for this query (if it isn't already cached), and return it as a the result of the `useLazyLoadQuery` call. We'll go into more detail about how to show loading states in the [Loading States with Suspense](../loading-states/) section, and how Relay uses cached data in the [Reusing Cached Data For Rendering](../../reusing-cached-data/) section.
+* Note that if you re-render your component and pass *different query variables* than the ones originally used, it will cause the query to be fetched again with the new variables, and potentially re-render with different data.
+* Finally, make sure you're providing a Relay environment using a [Relay Environment Provider](../../../api-reference/relay-environment-provider/) at the root of your app before trying to render a query.
+
+
+<DocsRating />