relay Documentation

Tutorial Arrays Lists (`website/docs/tutorial/arrays-lists.mdx`) Copy Section

Arrays and Lists

So far we’ve only dealt with components that have a single instance of the components they’re composed from. For example, we’re only showing a single Newsfeed story, and within that story there’s just a single author with a single profile picture. Let’s look at how to handle more than one of something.

GraphQL includes support for arrays, which in GraphQL are called lists. A field can be not only a single scalar value but an array of them, or not only a single edge but an array of edges. The schema specifies whether each field is a list or not, but, oddly, the GraphQL query syntax doesn’t distinguish between selecting a singular field and selecting a list — a quirky exception to the design principle that a GraphQL response should have the same shape as the query.

Request:

query MyQuery {
  viewer {
    contacts { // List of edges
      id // field on a single item
      name
    }
  }
}

Response:

{
  viewer: {
    contacts: [ // array in response
      {
        id: "123",
        name: "Chris",
      },
      {
        id: "789",
        name: "Sue",
      }
    ]
  }
}

As it happens, the schema in our example app has a topStories field that returns a list of Stories, as opposed to the topStory field we're currently using that returns just one.

To show multiple stories on our newsfeed, we just need to modify Newsfeed.tsx to use topStories.

Step 1 — Select a list in the fragment Copy Section

Open Newsfeed.tsx and find NewsfeedQuery. Replace topStory with topStories, and run npm run relay.

const NewsfeedQuery = graphql`
  query NewsfeedQuery {
    // change-line
    topStories {
      ...StoryFragment
    }
  }
`;

Step 2 — Map over the list in the component Copy Section

In the Newsfeed component, data.topStories will now be an array of fragment refs, each of which can be passed to a Story child component to render that story:

export default function Newsfeed({}) {
  const data = useLazyLoadQuery<NewsfeedQueryType>(NewsfeedQuery, {});
  // change-line
  const stories = data.topStories;
  return (
    <div className="newsfeed">
      // change-line
      {stories.map(story => <Story story={story} />)}
    </div>
  );
}

Step 3 — Add a React key based on the node ID Copy Section

At this point, you should see multiple stories on the screen! It's beginning to look like a proper newsfeed app.

However, we're also getting a React warning that we're rendering an array of components without providing a key attribute.

It's always important to heed this warning, and more specifically to base keys on the identity of the things being displayed, rather than simply their indices in the array. This allows React to handle reordering and deleting items from the list correctly, since it knows which items are which even if their order changes.

Luckily, GraphQL nodes generally have IDs. We can simply select the id field of story and use it as a key:

const NewsfeedQuery = graphql`
  query NewsfeedQuery {
    topStories {
      // change-line
      id
      ...StoryFragment
    }
  }
`;

...

export default function Newsfeed({}) {
  const data = useLazyLoadQuery<NewsfeedQueryType>(NewsfeedQuery, {});
  const stories = data.topStories;
  return (
    <div className="newsfeed">
      {stories.map(story => (
        <Story
          // change-line
          key={story.id}
          story={story}
        />
      ))}
    </div>
  );
}

With that, we've got a collection of Stories on the screen. It's worth pointing out that here we're mixing individual fields with fragment spreads in the same place in our query. This means that Newsfeed can read the fields it cares about (directly from useLazyLoadQuery) while Story can read the fields it cares about (via useFragment). The same object both contains Newsfeed's selected field id and is also a fragment key for StoryFragment.

:::tip
GraphQL Lists are only the most basic way of dealing with collections of things. We’ll build on them to do pagination and infinite scrolling later in the tutorial, using a special system called Connections. You’ll want to use Connections in most situations where you have a collection of items — although you’ll still use GraphQL Lists as a building block.
:::

Onward!

Tutorial Fragments 1 (`website/docs/tutorial/fragments-1.mdx`) Copy Section

Fragments

Fragments are one of the distinguishing features of Relay. They let each component declare its own data needs independently, while retaining the efficiency of a single query. In this section, we’ll show how to split a query up into fragments.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

To start with, let’s say we want our Story component to show the date that the story was posted. To do that, we need some more data from the server, so we’re going to have to add a field to the query.

Go to Newsfeed.tsx and find NewsfeedQuery so that you can add the new field:

const NewsfeedQuery = graphql`
  query NewsfeedQuery {
    topStory {
      title
      summary
      // change-line
      createdAt // Add this line
      poster {
        name
        profilePicture {
          url
        }
      }
      thumbnail {
        url
      }
    }
  }
`;

Now we've updated the query, we need to run the Relay compiler so that it knows about the updated Graphql query by running npm run relay.

Next, go to Story.tsx and modify it to display the date:

// change-line
import Timestamp from './Timestamp';

type Props = {
  story: {
    // change-line
    createdAt: string; // Add this line
    ...
  };
};

export default function Story({story}: Props) {
  return (
    <Card>
      <PosterByline poster={story.poster} />
      <Heading>{story.title}</Heading>
      // change-line
      <Timestamp time={story.createdAt} /> // Add this line
      <Image image={story.thumbnail} width={400} height={400} />
      <StorySummary summary={story.summary} />
    </Card>
  );
}

The date should now appear. And thanks to GraphQL, we didn't have to write and deploy any new server code.

But if you think about it, why should you have had to modify Newsfeed.tsx? Shouldn’t React components be self-contained? Why should Newsfeed care about the specific data required by Story? What if the data was required by some child component of Story way down in the hierarchy? What if it was a component that was used in many different places? Then we would have to modify many components whenever its data requirements changed.

To avoid these and many other problems, we can move the data requirements for the Story component into Story.tsx.

We do this by splitting off Story’s data requirements into a fragment defined in Story.tsx. Fragments are separate pieces of GraphQL that the Relay compiler stitches together into complete queries. They allow each component to define its own data requirements, without paying the cost at runtime of each component running its own queries.

Let’s go ahead and split Story’s data requirements into a fragment now.

Step 1 — Define a fragment Copy Section

Add the following to Story.tsx (within src/components) above the Story component:

import { graphql } from 'relay-runtime';

const StoryFragment = graphql`
  fragment StoryFragment on Story {
    title
    summary
    createdAt
    poster {
      name
      profilePicture {
        url
      }
    }
    thumbnail {
      url
    }
  }
`;

Note that we’ve taken all of the selections from within topStory in our query and copied them into this new Fragment declaration. Like queries, fragments have a name (StoryFragment), which we’ll use in a moment, but they also have a GraphQL type (Story) that they’re “on”. This means that this fragment can be used whenever we have a Story node in the graph.

Step 2 — Spread the fragment Copy Section

Go to Newsfeed.tsx and modify NewsfeedQuery to look like this:

const NewsfeedQuery = graphql`
  query NewsfeedQuery {
    topStory {
      // change-line
      ...StoryFragment
    }
  }
`;

We’ve replaced the selections inside topStory with StoryFragment. The Relay compiler will make sure that all of Story’s data gets fetched from now on, without having to change Newsfeed.

Step 3 — Call useFragment Copy Section

You’ll notice that Story now renders an empty card! All the data is missing! Wasn’t Relay supposed to include the fields selected by the fragment in the story object obtained from useLazyLoadQuery()?

The reason is that Relay hides them. Unless a component specifically asks for the data for a certain fragment, that data will not be visible to the component. This is called data masking, and enforces that components don’t implicitly rely on another component’s data dependencies, but declare all of their dependencies within their own fragments. This keeps components self-contained and maintainable.

Without data masking, you could never remove a field from a fragment, because it would be hard to verify that some other component somewhere wasn’t using it.

To access the data selected by a fragment, we use a hook called useFragment. Modify Story to look like this:

import { useFragment } from 'react-relay';

export default function Story({story}: Props) {
  const data = useFragment(
    // color1
    StoryFragment,
    // color2
    story,
  );
  return (
    <Card>
      <Heading>{data.title}</Heading>
      <PosterByline poster={data.poster} />
      <Timestamp time={data.createdAt} />
      <Image image={data.thumbnail} width={400} height={400} />
      <StorySummary summary={data.summary} />
    </Card>
  );
}

useFragment takes two arguments:

• The GraphQL tagged string literal for the fragment we want to read
• The same story object as we used before, which comes from the place within a GraphQL query where we spread the fragment. This is called a fragment key.

It returns the data selected by that fragment.

:::tip
We’ve rewritten story to data (the data returned by useFragment) in all of the JSX here; make sure to do the same in your copy of the component, or it won't work.
:::

Fragment keys are the places in a GraphQL query response where a fragment was spread. For example, given the Newsfeed query:

query NewsfeedQuery {
  topStory {
    ...StoryFragment
  }
}

Then if queryResult is the object returned by useLazyLoadQuery, queryResult.topStory will be a fragment key for StoryFragment.

Technically, queryResult.topStory is an object that contains some hidden fields that tell Relay's useFragment where to look for the data it needs. The fragment key specifies both which node to read from (here there's just one story, but soon we'll have multiple stories), and what fields can be read out (the fields selected by that specific fragment). The useFragment hook then reads that specific information out of Relay's local data store.

:::note
As we'll see in later examples, you can spread multiple fragments into the same place in a query, and also mix fragment spreads with directly-selected fields.
:::

Step 4 — TypeScript types for fragment refs Copy Section

To complete the fragmentization, we also need to change the type definition for Props so that TypeScript knows this component expects to receive a fragment key instead of the raw data.

Recall that when you spread a fragment into a query (or another fragment), the part of the query result corresponding to where the fragment is spread becomes a fragment key for that fragment. This fragment key is the object that you pass to a component to tell it where in the graph to read the fragment from.

To make this type-safe, Relay generates a type that represents the fragment key for that specific fragment — this way, if you try to use a component without spreading its fragment into your query, you won’t be able to provide a fragment key that satisfies the type system. Here are the changes we need to make:

// change-line
import type {StoryFragment$key} from './__generated__/StoryFragment.graphql';

type Props = {
  // change-line
  story: StoryFragment$key;
};

With that done, we have a Newsfeed that no longer has to care what data Story requires, yet can still fetch that data up-front within its own query.

Exercise Copy Chapter

The PosterByline component used by Story renders the poster’s name and profile picture. Use these same steps to fragmentize PosterByline. You need to:

• Declare a PosterBylineFragment on Actor and specify the fields it needs (name, profilePicture). The Actor type represents a person or organization that can post a story.
• Spread that fragment within poster in StoryFragment.
• Call useFragment to retrieve the data.
• Update the Props to accept a PosterBylineFragment$key as the poster prop.

It’s worth going through these steps a second time, to get the mechanics of using fragments under your fingers. There are a lot of parts here that need to slot together in the right way.

Once you’ve done that, let’s look at a basic example of how fragments help an app to scale.

Reusing a Fragment in Multiple Places Copy Chapter

A fragment says, given some graph node of a particular type, what data to read from that node. The fragment key specifies which node in the graph the data is selected from. A re-usable component that specifies a fragment can retrieve the data from different parts of the graph in different contexts, by being passed a different fragment key.

For example, notice that the Image component is used in two places: directly within Story for the story’s thumbnail image, and also within PosterByline for the poster’s profile pic. Let’s fragmentize Image and see how it can select the data it needs from different places in the graph according to where it is used.

Step 1 — Define the fragment Copy Section

Open up Image.tsx and add a Fragment definition:

import { graphql } from 'relay-runtime';

const ImageFragment = graphql`
  fragment ImageFragment on Image {
    url
  }
`;

Step 2 — Spread the fragment Copy Section

Go back to StoryFragment and PosterBylineFragment and spread ImageFragment into it in each place where the Image component is what’s using the data:

const StoryFragment = graphql`
  fragment StoryFragment on Story {
    title
    summary
    postedAt
    poster {
      ...PosterBylineFragment
    }
    thumbnail {
      // change-line
      ...ImageFragment
    }
  }
`;

const PosterBylineFragment = graphql`
  fragment PosterBylineFragment on Actor {
    name
    profilePicture {
      // change-line
      ...ImageFragment
    }
  }
`;

Step 3 — Call useFragment Copy Section

Modify the Image component to read the fields using its fragment, and also modify its Props to accept the fragment key:

import { useFragment } from 'react-relay';
import type { ImageFragment$key } from "./__generated__/ImageFragment.graphql";

type Props = {
  image: ImageFragment$key;
  ...
};

function Image({image}: Props) {
  const data = useFragment(ImageFragment, image);
  return <img key={data.url} src={data.url} ... />
}

Step 4 — Modify once, enjoy everywhere Copy Section

Now that we’ve fragmentized Image’s data requirements and co-located them within the component, we can add new data dependencies to Image without modifying any of the components that use it.

For example, let’s add an altText label for accessibility to the Image component.

Edit ImageFragment as follows:

const ImageFragment = graphql`
  fragment ImageFragment on Image {
    url
    // change-line
    altText
  }
`;

Now, without editing Story, Newsfeed, or any other component, all of the images within our query will have alt text fetched for them. So we just need to modify Image to use the new field:

function Image({image}) {
  // ...
  <img
    // change-line
    alt={data.altText}
  //...
}

Now both the story thumbnail image and the poster’s profile pic will have an alt text. (You can use your browser’s Elements inspector to verify this.)

You can imagine how beneficial this is as your codebase gets larger. Each component is self-contained, no matter how many places it’s used in! Even if a component is used in hundreds of places, you can add or remove fields from its data dependencies at will. This is one of the main ways that Relay helps you scale with the size of your app.

Fragments are the building blocks of Relay apps. As such, a lot of Relay features are based on fragments. We’ll look at a few of them in the next sections.

Fragment arguments and field arguments Copy Chapter

Currently the Image component fetches images at their full size, even if they’ll be displayed at a smaller size. This is inefficient! The Image component takes a prop that says what size to show the image at, so it’s controlled by the component that uses Image. We’d like in a similar way for the component that uses Image to say what size of image to fetch within its fragment.

GraphQL fields can accept arguments that give the server additional information to fulfill our request. For example, the url field on the Image type accepts height and width arguments that the server incorporates into the URL — if we have this fragment:

fragment Example1 on Image {
  url
}

we might get the URL such as /images/abcde.jpeg

— whereas if we have this fragment:

fragment Example2 on Image {
  url(height: 100, width: 100)
}

we might get a URL like /images/abcde.jpeg?height=100&width=100

Now of course, we don’t want to just hard-code a specific size into ImageFragment, because we’d like the Image component to fetch a different size in different contexts. To do that, we can make the ImageFragment accept fragment arguments so that the parent component can specify how large of an image should be fetched. These fragment arguments can then be passed into specific fields (in this case url) as field arguments.

To do that, edit ImageFragment as follows:

const ImageFragment = graphql`
  fragment ImageFragment on Image
    @argumentDefinitions(
      // color1
      width: {
        // color2
        type: "Int",
        // color3
        defaultValue: null
      }
      height: {
        type: "Int",
        defaultValue: null
      }
    )
  {
    url(
      // color4
      width: $width,
      // color4
      height: $height
    )
    altText
  }
`;

Let’s break this down:

• We’ve added an @argumentDefinitions directive to the fragment declaration. This says what arguments the fragment accepts. For each argument, we give:
  • The name of the argument
  • Its type (which can be any GraphQL scalar type)
  • Optionally a default value — in this case, the default value is null, which lets us fetch the image at its inherent size. If no default value is given, then the argument is required at every place the fragment is used.
• Then we populate an argument to a GraphQL field by using the fragment argument as a variable. Here the field arguments and fragment arguments have the same name (as will often be the case), but note: width: is the field argument while $width is the variable created by the fragment argument.

Now the fragment accepts an argument that it passes along to the server via one of the fields it selects.

Deep dive: GraphQL Directives

The syntax for fragment arguments may look rather clumsy. This is because it is based on directives, a system for extending the GraphQL language. In GraphQL, any symbol starting with @ is a directive. Their meaning isn't defined by the GraphQL spec, but is up to the specific client or server implementation.

Relay defines several directives to support its features — fragment arguments for one. These directives are not sent to the server, but give instructions to the Relay compiler at build time.

The GraphQL spec actually does define the meaning of three directives:

• @deprecated is used in schema definitions and marks a field as deprecated.
• @include and @skip can be used to make the inclusion of a field conditional.

Besides these, GraphQL servers can specify additional directives as part of their schemas. And Relay has its own build-time directives, which allow us to extend the language a bit without changing its grammar.

Now the different fragments using Image can pass in the appropriate size for each image:

const StoryFragment = graphql`
  fragment StoryFragment on Story {
    title
    summary
    postedAt
    poster {
      ...PosterBylineFragment
    }
    thumbnail {
      // change-line
      ...ImageFragment @arguments(width: 400)
    }
  }
`;

const PosterBylineFragment = graphql`
  fragment PosterBylineFragment on Actor {
    name
    profilePicture {
      // change-line
      ...ImageFragment @arguments(width: 60, height: 60)
    }
  }
`;

Now if you look at the images that our app downloads, you’ll see they’re of the smaller size, saving network bandwidth. Note that although we used integer literals for the value of our fragment arguments, we can also use variables supplied at runtime, as we'll see in later sections.

Field arguments (e.g. url(height: 100)) are a feature of GraphQL itself, while fragment arguments (as in @argumentDefinitions and @arguments) are Relay-specific features. The Relay compiler processes these fragment arguments when it combines fragments into queries.

Summary Copy Chapter

Fragments are the most distinctive aspect of how Relay uses GraphQL. We recommend that every component that displays data and cares about the semantics of that data (so not just a typographic or formatting component) use a GraphQL fragment to declare its data dependencies.

• Fragments help you scale: No matter how many places a component is used, you can update its data dependencies in a single place.
• Fragment data needs to be read out with useFragment.
• useFragment takes a fragment key which says where in the graph to read from.
• Fragment keys come from places in a GraphQL response where that fragment was spread.
• Fragments can define arguments which are used at the point they’re spread. This allows them to be tailored to each situation they're used in.

We'll be revisiting many other features of fragments, such as how to refetch the contents of a single fragment without refetching the entire query. First, though, let's make this newsfeed app more newsfeed-like by learning about arrays.

Tutorial Graphql (`website/docs/tutorial/graphql.mdx`) Copy Section

GraphQL and Relay

This section is an overview to situate Relay in relation to GraphQL, React, and the other parts of the stack. Don’t worry about understanding every detail, just try to get the gist and then proceed to the next section to start working with code. Much more specifics will be explained as we go through working examples throughout the tutorial.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

GraphQL is a language for querying and modifying data on servers. The unique thing about GraphQL is that rather than having a fixed set of API endpoints, your server provides a palette of options that the client can use to request any combination of data that it may need. This allows front-end developers to move more quickly because there is no need to write and deploy new endpoints as data requirements change. It also means that when a new version of the client is released, it can request just the data it needs, without extra fields leftover for compatibility with older versions.

GraphQL provides a unified interface for querying data across any kind of back-end. Whether your data is in a relational SQL database, a graph-oriented database, or an armada of microservices, a GraphQL server can collect the data from multiple back-ends and send it to the client in a single response, which is more efficient than issuing separate queries to each service from the client.

In a traditional HTTP API, there are URLs that each respond with a fixed set of information:

Request:
GET /person?id=24601

Response:
{"id": "24601", "name": "Jean Valjean", "age": 64, "occupation": "Mayor"}

In GraphQL, the client asks for the specific information that it wants, and the server responds with just the information that was requested:

Request:
query {
  person(id: "24601") {
    name
    occupation
  }
}

Response:
{
  "person": {
    "name": "Jean Valjean",
    "occupation": "Mayor"
  }
}

Notice that only the specific fields that the client requested were included in the response.

As the name suggests, GraphQL organizes data into a graph. The graph consists of nodes (like objects or records) and edges (pointers from one node to another):

GraphQL lets you follow those edges from one node to another and ask for information about each node that you visit. For example, here we go from a person to their city and get information about the city:

query {
  person(id: "24601") {
    name
    occupation
    location {
      name
      population
    }
  }
}

{
  "person": {
    "name": "Jean Valjean",
    "occupation": "Mayor",
    "location": {
      "name": "Montreuil-sur-Mer",
      "population": 1935
    }
  }
}

This means we can retrieve information about a whole panoply of objects all in one query — in other words, you can efficiently get all the data for a screen in a single request instead of sending many requests one after the other. But you achieve this without writing and maintaining a separate endpoint for each screen in your UI.

Instead, your GraphQL server provides a schema, which describes what kinds of nodes there are, how they’re connected, and what information each node contains. Then, you pick and choose from this schema to select the information you want.

The example app in this tutorial is a newsfeed app, so its schema consists of types such as

• Story, which represents a newsfeed story — it has fields such as its title, an image, and an edge to the person or organization who posted it
• Person, with information such as their name, email, and a list of friends (which are edges to other Persons).
• Viewer, which represents the person viewing the app and has information like their list of newsfeed stories
• Image, which has a URL for the image itself as well as an alt text description.

The GraphQL language includes a type system and language for specifying the schema. Here’s a snippet from the schema definition for our example app — don’t worry about every detail, it’s just to give you a general idea:

// A newsfeed story. It has fields, some of which are scalars (e.g. strings
// and numbers) and some that are edges that point to other nodes in the graph,
// such as the 'thumbnail' and 'poster' fields:
type Story {
  id: ID!
  category: Category
  title: String
  summary: String
  thumbnail: Image
  poster: Actor
}

// An Actor is an entity that can do something on the site. This is an
// interface that multiple different types can implement, in this case
// Person and Organization:
interface Actor {
  id: ID!
  name: String
  profilePicture: Image
}

// This is a specific type that implements that interface:
type Person implements Actor {
  id: ID!
  name: String
  email: String
  profilePicture: Image
  location: Location
}

// The schema also lets you define enums, such as the category
// of a newsfeed story:
enum Category {
  EDUCATION
  NEWS
  COOKING
}

Besides queries, GraphQL also lets you send mutations that ask the server to update its data. If queries are analogous to HTTP GET requests, then mutations are the equivalent of POST requests. Like POSTs, they let the server respond with updated data. GraphQL also has subscriptions which allow for an open connection for realtime updates.

(GraphQL is usually implemented over HTTP, so queries and mutations are not only analogous to GET and POST, but may be sent as such as well.)

Now that we’ve talked about GraphQL, let’s talk about Relay. It has a few different parts and pieces that we’ll briefly go over before diving into the code.

Relay is a data management library for the client that’s oriented around GraphQL, but uses it in a very specific way that gets the most benefit from it.

For the best performance, you want your app to issue a single request at the beginning of each screen or page instead of having individual components issue their own requests. But the problem with that is that it couples components and screens together, creating a big maintenance problem: If you need some additional data in a specific component, you have to find every screen where that component is used and add the new field to that screen’s query. On the other hand, if you remove the need for a particular field, you have to remove that field from every query again — but this time, are you sure the field isn’t still in use by some other component? It becomes very difficult to maintain these big screen-wide queries.

Relay’s unique strength is to avoid this tradeoff by letting each component declare its own data requirements locally, but then stitching those requirements together into larger queries. That way you get both performance and maintainability.

Relay does this with a compiler that scans your JavaScript code for fragments of GraphQL, and then stitches those fragments together into complete queries.

Besides the compiler, Relay has runtime code that manages the fetching and processing of GraphQL. It maintains a local cache of all the data that has been retrieved (called the Store), and vends out to each component the data that belongs to it:

The advantage of having a centralized Store is that it lets you keep your data consistent when it’s updated. For instance, if your UI has a way for somebody to edit their name, then you can make that update in a single place and every component that displays that person’s name will see the new information, even if they’re on different screens and therefore used different queries to initially retrieve the data. This is because Relay normalizes the data as it comes in, meaning that it merges all the data it sees for a single graph node into one place, so it doesn’t have multiple copies of the same node.

Indeed, Relay doesn’t just query data, it provides functions to manage the entire lifecycle of querying and updating, including support for optimistic updates and rollbacks. You can paginate, refresh data — all of the basic operations you’ll need to create a UI. Whenever data in the Store is updated, Relay efficiently re-renders just those components that are displaying that particular data.

Summary Copy Chapter

GraphQL is a language for modeling data as a graph and querying that data from a server (as well as updating the data). Relay is a React-based client library for GraphQL that lets you build up queries from individual fragments that are co-located with each React component. Once the data has been queried, Relay maintains consistency and re-renders components as the data is updated.

Tutorial Interfaces Polymorphism (`website/docs/tutorial/interfaces-polymorphism.mdx`) Copy Section

GraphQL Types, Interfaces, and Polymorphism

In this section, we’ll see how to treat different types of nodes differently. You might notice that some of the newsfeed stories in the example app are posted by people, while others are posted by organizations. In this example, we'll enhance our hovercard by writing a fragment that selects people-specific information about people and organization-specific information about organizations.

We’ve alluded to the fact that GraphQL nodes aren’t just random bags of fields — they have types. Your GraphQL schema defines what fields each type has. For instance, it might define the Story type like this:

type Story {
  id: ID!
  title: String
  summary: String
  createdAt: Date
  poster: Actor
  image: Image
}

Here, some of the fields are scalars (like String and ID). Others are types defined elsewhere in the schema, like Image — these fields are edges to nodes of those specific types. The ! on ID! means that field is non-nullable. In GraphQL, fields are normally nullable and non-nullability is the exception.

Fragments are always “on” a particular type. In our example above, StoryFragment is defined on Story. This means that you can only spread it into places in a query where a Story node is expected. And it means that the fragment can select just those fields that exist on the Story type.

Of particular interest is the Actor type used for the poster field. This type is an interface. That means that the poster of a story can be a Person, a Page, an Organization, or any other type of entity that meets the specifications for being an “Actor”.

The GraphQL schema in our example app defines an Actor as follows:

interface Actor {
  name: String
  profilePicture: Image
  joined: DateTime
}

Not coincidentally this is exactly the information that we’re displaying here. There are two types in the schema that implement Actor, meaning that they include all the fields defined in Actor. They are declared as such:

type Person implements Actor {
  id: ID!
  name: String
  profilePicture: Image
  joined: DateTime
  email: String
  location: Location
}

type Organization implements Actor {
  id: ID!
  name: String
  profilePicture: Image
  joined: DateTime
  organizationKind: OrganizationKind
}

Both of these types have name , profilePicture, and joined, so they can both declare that they implement Actor and thus can be used wherever an Actor is called for in the schema and in fragments. They also have other fields that are distinct to each particular type.

Let’s see how to work with interfaces more by extending the PosterDetailsHovercardContentsBody component to display the location of a Person or the organization kind of an Organization. These are fields that are only present on those specific types, not on the Actor interface.

Right now, if you’ve followed along so far, it should have a fragment defined like this (in PosterDetailsHovercardContents.tsx):

fragment PosterDetailsHovercardContentsBodyFragment on Actor {
  name
  joined
  profilePicture {
    ...ImageFragment
  }
}

If you try to add a field like organizationKind to this fragment, you’ll get an error from the Relay compiler:

✖︎ The type `Actor` has no field organizationKind

This is because when we define a fragment as being on an interface, we can only use fields from that interface. To use fields from a specific type that implements the interface, we use a type refinement to tell GraphQL we’re selecting fields from that type:

fragment PosterDetailsHovercardContentsBodyFragment on Actor {
  name
  joined
  profilePicture {
    ...ImageFragment
  }
  // change
  ... on Organization {
    organizationKind
  }
  // end-change
}

Go ahead and add this now. You can also add a type refinement for Person:

fragment PosterDetailsHovercardContentsBodyFragment on Actor {
  name
  joined
  profilePicture {
    ...ImageFragment
  }
  ... on Organization {
    organizationKind
  }
  // change
  ... on Person {
    location {
      name
    }
  }
  // end-change
}

When you select a field that’s only present on some of the types that implement an interface, and the node you’re dealing with is of a different type, then you simply get null for the value of that field when you read it out. With that in mind, we can modify the PosterDetailsHovercardContentsBody component to show the location of people and organization kind of organizations:

import OrganizationKind from './OrganizationKind';

function PosterDetailsHovercardContentsBody({ poster }: Props): React.ReactElement {
  const data = useFragment(PosterDetailsHovercardContentsBodyFragment, poster);
  return (
    <>
      <Image image={data.profilePicture} width={128} height={128} className="posterHovercard__image" />
      <div className="posterHovercard__name">{data.name}</div>
      <ul className="posterHovercard__details">
         <li>Joined <Timestamp time={poster.joined} /></li>
         // change
         {data.location != null && (
           <li>{data.location.name}</li>
         )}
        {data.organizationKind != null && (
          <li><OrganizationKind kind={data.organizationKind} /></li>
         )}
         // end-change
      </ul>
    </>
  );
}

You should now see the location of people, and the organization kind for organizations:

By the way, we can now understand why we had ... on Actor in the example earlier. The node field can return a node of any type because any ID could be given at runtime. So the type that it gives us is Node, a very generic interface that can be implemented by anything that has an id field. We needed a type refinement to use fields from the Actor interface.

:::note
In the GraphQL spec and other sources, type refinements are called inline fragments. We call them “type refinements” instead because this terminology is more descriptive and less confusing.
:::

:::tip
If you need to do something totally different depending on what type it is, you can select a field called __typename, which returns a string with the name of the concrete type that you got (e.g., "Person" or "Organization"). This is a built-in feature of GraphQL.
:::

Summary Copy Chapter

The ... on Type {} syntax allows us to select fields that are only present in a specific type that implements an interface.

Tutorial Mutations Updates (`website/docs/tutorial/mutations-updates.mdx`) Copy Section

Mutations & Updates

In this chapter we’ll learn how to update data on the server and client. We’ll go through two main examples:

• Implementing a Like button for newsfeed stories
• Implementing the ability to post comments on a newsfeed story

Updating data is a complicated problem domain, and Relay handles many aspects of it automatically, while also giving you a lot of manual control so that your app can be as robust as possible in handling the cases that can arise.

First let’s distinguish two terms:

• A mutation is when you ask the server to perform some action that modifies data on the server. This is a feature of GraphQL that is analogous to an HTTP POST.
• An update is when you modify Relay’s local client-side data store.

The client doesn’t have the ability to directly manipulate individual pieces of data on the server side. Rather, mutations are opaque, high-level requests that express the user’s intent — for example, that the user friended somebody, joined a group, posted a comment, liked a particular newsfeed story, blocked somebody, or deleted a comment. (The GraphQL schema defines what mutations are available, as well as the input parameters that each mutation accepts.)

Mutations can have far-reaching and unpredictable effects on the state of the graph. For example, let’s say you join a group. Many things can change:

• Your name gets added to the Group Members list
• The group’s membership count gets incremented
• The group gets added to your list of groups
• Members-only posts appear in the group’s post feed
• Your recommended groups may change
• The group’s admins may get notifications
• Many other non-user-visible effects such as logging, training models, or sending emails
• Etc. etc. etc.

In general, it’s impossible to know what the full downstream effect of a mutation may be. So after asking the server to perform a mutation, the client just has to do its best to update its local data store, keeping the data as consistent as reasonably possible. It does this by asking the server for specific updated data as part of the mutation response, and by imperative code — called an updater — that fixes up the store to keep it consistent.

There is no principled solution that covers every case. Even if it were possible to know the full effect of a mutation on the graph, there are even circumstances where we don’t want to show updated data right away. For example, if you go to somebody’s profile page and block them, you don’t want for everything shown on that page to immediately disappear. The question of what data to update is ultimately a UI design decision.

Relay tries to make it as easy as possible to update data in response to a mutation. For example, if you want to update a certain component, you can spread its fragment into your mutation, which asks the server to send updated data for whatever was selected by that fragment. For other cases, you have to manually write an updater that modifies Relay’s local data store imperatively. We’ll look at all of these cases below.

Implementing a Like Button Copy Chapter

Let’s dip our toes in the water by implementing the Like button for Newsfeed stories. Luckily we already have a Like button prepared, so open up Story.tsx and drop it in to the Story component, remembering to spread its fragment into Story’s fragment:

// change-line
import StoryLikeButton from './StoryLikeButton';

...

const StoryFragment = graphql`
  fragment StoryFragment on Story {
    title
    summary
    // ... etc
    // change-line
    ...StoryLikeButtonFragment
  }
`;

...

export default function Story({story}: Props) {
  const data = useFragment(StoryFragment, story);
  return (
    <Card>
      <PosterByline person={data.poster} />
      <Heading>{data.title}</Heading>
      <Timestamp time={data.posterAt} />
      <Image image={story.thumbnail} width={400} height={400} />
      <StorySummary summary={data.summary} />
      // change-line
      <StoryLikeButton story={data} />
      <StoryCommentsSection story={data} />
    </Card>
  );
}

Now let’s take a look at StoryLikeButton.tsx. Currently, it is a button that doesn’t do anything, along with a like count.

You can look at its fragment to see that it fetches a field likeCount for the like count and doesViewerLike to determine whether the Like button is highlighted (it’s highlighted if the viewer likes the story, i.e. if doesViewerLike is true):

const StoryLikeButtonFragment = graphql`
  fragment StoryLikeButtonFragment on Story {
    id
    likeCount
    doesViewerLike
  }
`;

We want to make it so that when you press the Like button

1. The story gets “liked” on the server
2. Our local client copy of the “likeCount” and “doesViewerLike” fields get updated.

To do that, we need to write a GraphQL mutation. But first...

Anatomy of a Mutation Copy Chapter

The GraphQL mutation syntax is going to be confusing unless you first understand the following:

GraphQL has two different request types, Queries and Mutations — and they work in exactly the same way. This is analogous to how HTTP has GET and POST: technically the only difference is that POST requests are intended to cause effects while GET requests do not. Similarly, a Mutation is exactly like a Query, except that the Mutation is expected to cause things to happen. This means:

• A mutation is part of our client code
• A mutation declares variables that let the client pass data to the server
• The server implements individual fields. A given mutation composes together those fields and passes its variables in as field arguments.
• Each field yields data of a particular type — either scalar or an edge to some other graph node — which is returned to the client if that field is selected. In the case of edges, further fields are selected from the node being linked to.

The only difference is that, in a mutation, selecting a field makes something happen, as well as returning data.

The Like Mutation Copy Chapter

With that in mind, this is what our mutation is going to look like — go ahead and add this declaration to the file:

const StoryLikeButtonLikeMutation = graphql`
  mutation StoryLikeButtonLikeMutation(
    // color1
    $id: ID!,
    // color1
    $doesLike: Boolean!,
  ) {
    // color2
    likeStory(
      // color3
      id: $id,
      // color3
      doesLike: $doesLike
    ) {
      // color4
      story {
        // color5
        id
        // color5
        likeCount
        // color5
        doesViewerLike
      }
    }
  }
`;

This is a lot, let’s break it down:

• The mutation is named StoryLikeButton + Like + Mutation because it must begin with the module name, and end with the GraphQL operation.
• The mutation declares variables which are passed from the client to the server when the mutation is dispatched. Each variable has a name ($id, $doesLike) and a type (ID!, Boolean!). The ! after the type indicates that it is required, not optional.
• The mutation selects a mutation field defined by the GraphQL schema. Each mutation field that the server defines corresponds to some action that the client can request of the server, such as liking a story.
  • The mutation field takes arguments (just like any field can do). Here we pass in the mutation variables that we declared as the argument values — for example, the doesLike field argument is set to be the $doesLike mutation variable.
• The likeStory field returns an edge to a node that represents the mutation response. We can select various fields in order to receive updated data. The fields that are available in the mutation response are specified by the GraphQL schema.
  • We select the story field, which is an edge to the Story that we just liked.
  • We select specific fields from within that Story to get updated data. These are the same fields that a query could select about a Story — in fact, the same fields we selected in our fragment.

When we send the server this mutation, we’ll get a response that, just like with queries, matches the shape of the mutation that we sent. For example, the server might send this back to us:

{
  "likeStory": {
    "story": {
      "id": "34a8c",
      "likeCount": 47,
      "doesViewerLike": true
    }
  }
}

and our job will be to update the local data store to incorporate this updated information. Relay will handle this in simple cases, while in more complex cases it will require custom code to update the store intelligently.

But we’re getting ahead of ourselves — let’s make that button trigger the mutation. Here’s what our component looks like now — we need to hook up the onLikeButtonClicked event to execute StoryLikeButtonLikeMutation.

function StoryLikeButton({story}) {
  const data = useFragment(StoryLikeButtonFragment, story);
  function onLikeButtonClicked() {
    // To be filled in
  }
  return (
    <>
      <LikeCount count={data.likeCount} />
      <LikeButton value={data.doesViewerLike} onChange={onLikeButtonClicked} />
    </>
  )
}

To do that, we add a call to useMutation:

// change-line
import {useMutation, useFragment} from 'react-relay';

function StoryLikeButton({story}) {
  const data = useFragment(StoryLikeButtonFragment, story);
  // change-line
  const [commitMutation, isMutationInFlight] = useMutation(StoryLikeButtonLikeMutation);
  function onLikeButtonClicked() {
    // change
    commitMutation({
      variables: {
        id: data.id,
        doesLike: !data.doesViewerLike,
      },
    })
    // end-change
  }
  return (
    <>
      <LikeCount count={data.likeCount} />
      <LikeButton value={data.doesViewerLike} onChange={onLikeButtonClicked} />
    </>
  )
}

The useMutation hook returns a function commitMutation that we can call to tell the server to do stuff.

We pass in an option called variables where we give values for the variables defined by the mutation, namely id and doesViewerLike. This tells the server which story we’re talking about and whether the we are liking or un-liking it. The id of the story we’ve read from the fragment, while whether we like it or unlike it comes from toggling whatever the current value that we rendered is.

The hook also returns a boolean flag that tells us when the mutation is in flight. We can use that to make the user experience nicer by disabling the button while the mutation is happening:

<LikeButton
  value={data.doesViewerLike}
  onChange={onLikeButtonClicked}
  // change-line
  disabled={isMutationInFlight}
/>

With this in place, we should now be able to like a story!

How Relay Automatically Processes Mutation Responses Copy Chapter

But how did Relay know to update the story we clicked on? The server sent back a response with this form:

{
  "likeStory": {
    "story": {
      "id": "34a8c",
      "likeCount": 47,
      "doesViewerLike": true
    }
  }
}

Whenever the response includes an object with an id field, Relay will check if the store already contains a record with a matching ID in the id field of that record. If there is a match, Relay will merge the other fields from the response into the existing record. That means that, in this simple case, we don’t need to write any code to update the store.

Using Fragments in the Mutation Response Copy Chapter

Remember that mutations are just like queries. In order to make sure that the mutation response always contains the data we want to render, instead of having a separate set of fields that has to be manually kept up to date, we can simply spread fragments into our mutation response:

const StoryLikeButtonLikeMutation = graphql`
  mutation StoryLikeButtonLikeMutation(
    $id: ID,
    $doesLike: Boolean,
  ) {
    likeStory(id: $id, doesLike: $doesLike) {
      story {
        // change-line
        ...StoryLikeButtonFragment
      }
    }
  }
`;

Now if we add or remove data requirements, all of the necessary data (but no more) will be included with the mutation response. This is usually the smart way of writing mutation responses. You can spread in any fragment from any component, not just the component that triggers the mutation. This helps you keep your whole UI up to date.

Improving the UX with an Optimistic Updater Copy Chapter

Mutations take time to perform, yet we always want the UI to update immediately in some way to give the user feedback that they’ve taken an action. In the current example, the Like button is disabled while the mutation is happening, and then after the mutation is done, the UI is updated into the new state as Relay merges the updated data into its store and re-renders the affected components.

Oftentimes the best feedback will be to simply pretend the operation is already completed: for example, if you press the Like button, that buttons immediately goes into the same highlighted state that it will stay in whenever you see something you’ve already liked. Or take the example of posting a comment: We would like to immediately show your comment as having been posted. This is because mutations are usually fast and reliable enough that we don’t need to bother the user with a separate loading state for them. However, sometimes mutations do end in failure. In that case, we’d like to roll back the changes we made and return you to the state you were in before we tried the mutation: the comment we showed as being posted should go away, while the text of the comment should re-appear within the composer where you wrote it, so that the data isn’t lost if you want to try posting again.

Managing these so-called optimistic updates is complicated to do manually, but Relay has a robust system for applying and rolling back updates. You can even have multiple mutations in flight at the same time (say if the user clicks several buttons in sequence), and Relay will keep track of what changes need to be rolled back in case of a failure.

Mutations proceed in three phases:

• First there’s an optimistic update, where you update the local data store into whatever state you anticipate and want to show to the user immediately.
• Then you actually perform the mutation on the server. If it’s successful, the server responds with updated information which can be used in the third step.
• When the mutation is done, you roll back the optimistic update. If the mutation failed, you’re done — back to where you started. If the mutation succeeded, Relay merges simple changes into the store and then applies a concluding update that updates the local data store with the actual new information received from the server, plus whatever other changes you want to make.

With this background knowledge in hand, let’s go ahead and write an optimistic updater for our Like button so that it immediately updates to the new state when clicked.

Step 1 — Add the optimisticUpdater option to commitMutation Copy Section

Go to StoryLikeButton and add a new option to the call to commitMutation:

function StoryLikeButton({story}) {
  ...
  function onLikeButtonClicked(newDoesLike) {
    commitMutation({
      variables: {
        id: data.id,
        doesLike: newDoesLike,
      },
      // change
      optimisticUpdater: store => {
        // TODO fill in optimistic updater
      },
      // end-change
    })
  }
  ...
}

This callback receives a store argument which represents Relay’s local data store. It has various methods for reading and writing local data. All of the writes that we make in the optimistic updater will be applied immediately when the mutation is dispatched, and then rolled back when it is complete.

Step 2 — Create an Updatable Fragment Copy Section

We can read and write data in the local store by writing a special kind of fragment called an updatable fragment. Unlike a regular fragment, it doesn’t get spread into queries and sent to the server. Instead, it lets us read data out of the local store using the same GraphQL syntax we already know and love. Go ahead and add this fragment definition:

function StoryLikeButton({story}) {
  ...
      optimisticUpdater: store => {
        const fragment = graphql`
          fragment StoryLikeButton_updatable on Story
            // color1
            @updatable
          {
            likeCount
            doesViewerLike
          }
        `;
      },
  ...
}

It’s exactly like any other fragment but annotated with the @updatable directive.

Unlike normal fragments, updatable fragments are not spread into queries and do not select data to be fetched from the server. Instead, they select data that’s already in the Relay local data store so that the data may be updated.

Step 3 — Call readUpdatableFragment Copy Section

We pass this fragment, along with the original fragment ref that we received as a prop (which tells us which story we’re liking), to store.readUpdatableFragment. It returns a special object called updatableData:

function StoryLikeButton({story}) {
  ...
      optimisticUpdater: store => {
        const fragment = graphql`
          fragment StoryLikeButton_updatable on Story @updatable {
            likeCount
            doesViewerLike
          }
        `;
        const {
          // color1
          updatableData
        } = store.readUpdatableFragment<StoryLikeButton_updatable$key>(
          // color2
          fragment,
          // color3
          story
        );
      },
  ...
}

Step 4 — Modify the Updatable Data Copy Section

Now updatableData is an object representing our existing Story as it exists in the local store. We can read and write the fields listed in our fragment:

function StoryLikeButton({story}) {
  ...
      optimisticUpdater: store => {
        const fragment = graphql`
          fragment StoryLikeButton_updatable on Story @updatable {
            likeCount
            doesViewerLike
          }
        `;
        const { updatableData } =
          store.readUpdatableFragment<StoryLikeButton_updatable$key>(
            fragment,
            story
          );
        // change
        const alreadyLikes = updatableData.doesViewerLike;
        updatableData.doesViewerLike = !alreadyLikes;
        updatableData.likeCount += (alreadyLikes ? -1 : 1);
        // end-change
      },
  ...
}

In this example, we toggle doesViewerLike (so that clicking the button when you already like the story makes you un-like it) and increment or decrement the like count accordingly.

Relay records the changes we made to updatableData and will roll them back once the mutation is complete.

Now when you click the Like button, you should see the UI immediately update.

Adding Comments — Mutations on Connections Copy Chapter

The only thing that Relay can do completely automatically is what we’ve seen already: merge nodes in the mutation response with existing nodes that share the same ID in the store. For anything else, we have to give Relay some more information.

Let’s look at the case of Connections. We’ll implement the ability to post a new comment on a story.

The server’s mutation response only includes the newly-created comment. We have to tell Relay how to insert that story into the Connection between a story and its comments.

Head back over to StoryCommentsSection and add a component for posting a new comment, remembering to spread its fragment into our fragment:

// change-line
import StoryCommentsComposer from './StoryCommentsComposer';

const StoryCommentsSectionFragment = graphql`
  fragment StoryCommentsSectionFragment on Story
    ...
  {
    comments(after: $cursor, first: $count)
      @connection(key: "StoryCommentsSectionFragment_comments")
    {
      ...
    }
    // change-line
    ...StoryCommentsComposerFragment
  }
`

function StoryCommentsSection({story}) {
  ...
  return (
    <>
      // change-line
      <StoryCommentsComposer story={data} />
      ...
    </>
  );
}

We should now see a composer at the top of the comments section:

Now take a look inside StoryCommentsComposer.tsx:

function StoryCommentsComposer({story}) {
  const data = useFragment(StoryCommentsComposerFragment, story);
  const [text, setText] = useState('');
  function onPost() {
   // TODO post the comment here
  }
  return (
    <div className="commentsComposer">
      <TextComposer text={text} onChange={setText} onReturn={onPost} />
      <PostButton onClick={onPost} />
    </div>
  );
}

Step 1 — Define the Comment Posting Mutation Copy Section

Just like before, we need to define a mutation. It will send to the server the story ID and the text of the comment to be added:

const StoryCommentsComposerPostMutation = graphql`
  mutation StoryCommentsComposerPostMutation(
    $id: ID!,
    $text: String!,
  ) {
    postStoryComment(id: $id, text: $text) {
      commentEdge {
        node {
          id
          text
        }
      }
    }
  }
`;

Here, the schema allows us to select as part of the mutation response the newly-created edge to the newly-created comment. We select it and will use it to update the local store by inserting this edge into the Connection.

Step 2 — Call commitMutation to post it Copy Section

Now we use the useMutation hook to get access to the commitMutation callback, and call it in onPost:

function StoryCommentsComposer({story}) {
  const data = useFragment(StoryCommentsComposerFragment, story);
  const [text, setText] = useState('');
  // change-line
  const [commitMutation, isMutationInFlight] = useMutation(StoryCommentsComposerPostMutation);
  function onPost() {
    // change
    setText(''); // Reset the UI
    commitMutation({
      variables: {
        id: data.id,
        text,
      },
    })
    // end-change
  }
  ...
}

Step 3 — Add a Declarative Connection Handler Copy Section

At this point, we can find from the network logs that clicking Post will send a mutation request to the server — you can even see that the comment has been posted since it appears if you refresh the page. However, nothing happens in the UI. We need to tell Relay to append the newly-created comment to the Connection that goes from the story to its comments.

You’ll notice that in the mutation response that we wrote above we select commentEdge. This is the edge to the newly-created comment. We just need to tell Relay what Connections to add that edge to. Relay provides directives called @appendEdge, @prependEdge, and @deleteEdge that you put on the edge in the mutation response. Then when you run the mutation, you pass in the IDs of the Connections that you want to modify. Relay will append, prepend, or delete the edge from those connections as you specify.

We want our newly-created comment to appear at the top of the list, so we’ll use @prependEdge. Make the following additions to the mutation definition:

mutation StoryCommentsComposerPostMutation(
    $id: ID!,
    $text: String!,
    // change-line
    $connections: [ID!]!,
  ) {
    postStoryComment(id: $id, text: $text) {
      commentEdge
        // change-line
        @prependEdge(connections: $connections)
      {
        node {
          id
          text
        }
      }
    }
  }

We’ve added a variable called connections to the mutation. We’ll use this to pass in the Connections we want to update.

:::note
The $connections variable is only used as an argument to the @prependEdge directive, which is processed on the client by Relay. Because $connections is not passed as an argument to any field, it is not sent to the server.
:::

Step 4 — Pass in the Connection ID as a Mutation Variable Copy Section

We need to identify the Connection to add the new edge to. A Connection is identified with two pieces of information:

• Which node it’s off of — in this case, the Story we’re posting a comment to.
• The key provided in the @connection directive, which lets us distinguish connections in case more than one connection is off of the same node.

We pass this information in to the mutation variables using a special API provided by Relay:

// change-line
import {useFragment, useMutation, ConnectionHandler} from 'react-relay';

...

export default function StoryCommentsComposer({story}: Props) {
  ...
  function onPost() {
    setText('');
    // change
    const connectionID = ConnectionHandler.getConnectionID(
      data.id,
      'StoryCommentsSectionFragment_comments',
    );
    // end-change
    commitMutation({
      variables: {
        id: data.id,
        text,
        // change-line
        connections: [connectionID],
      },
    })
  }
  ...
}

The string "StoryCommentsSectionFragment_comments" that we pass to getConnectionID is the identifier that we used when fetching the connection in StoryCommentSection — just as a reminder, here's what that looked like:

const StoryCommentsSectionFragment = graphql`
  fragment StoryCommentsSectionFragment on Story
  ...
  {
    comments(after: $cursor, first: $count)
     @connection(key: "StoryCommentsSectionFragment_comments")
    {
      ...
  }
`;

Meanwhile, the argument data.id is the ID of the specific story that we’re connecting off of.

With this change, we should see the comment appear in the list of comments once the mutation is complete.

Summary Copy Chapter

Mutations let us ask the server to make changes.

• Just like Queries, Mutations are composed of fields, accept variables, and pass those variables as arguments to fields.
• The fields that are selected by a Mutation constitute the mutation response which we can use to update the Store.
• Relay automatically merges nodes in the response to nodes in the Store with matching IDs.
• The @appendEdge, @prependEdge, and @deleteEdge directives let us insert and remove items from the mutation response into Connections in the store.
• Updaters let us manually manipulate the store.
• Optimistic updaters run before the mutation begins and are rolled back when it is done.

Tutorial Organizing Mutations Queries And Subscriptions (`website/docs/tutorial/organizing-mutations-queries-and-subscriptions.mdx`) Copy Section

Organizing GraphQL Operations

In Relay, GraphQL operation and fragment names must be globally unique and must end with the GraphQL operation type (e.g. Query, Mutation, Subscription).

Recommended Organization For Mutations and Subscriptions Copy Section

Put Mutations in their own hook module so the name is closer to what the mutation does rather than which component invokes it. If the module name is correctly descriptive, it is fine to declare it in the same file.

If you are adding a Mutation for Post, like adding a comment to a post, you may create a new file titled useAddPostComment.js. Your mutation (in this file) will then be named useAddPostCommentMutation, which is a perfectly descriptive name.

Recommended Organization for Queries and Fragments Copy Section

Root components should have a single query that is tightly coupled to a component, since it describes that component's data dependencies. Queries and fragments should co-locate with their data-use code.

Tutorial Queries 1 (`website/docs/tutorial/queries-1.mdx`) Copy Section

Query Basics

In this section:

• We’ll take a React component that displays hard-coded placeholder data and modify it so that it fetches its data using a GraphQL query.
• We’ll learn how to use the TypeScript types that Relay generates from your GraphQL to ensure type safety.

With Relay, you fetch data using GraphQL Queries. A Query specifies a part of the GraphQL graph for your app to fetch, starting from some root node and traversing from node to node to retrieve a particular set of data in the shape of a tree.

Right now, our example app doesn’t fetch any data, it just renders some placeholder data that’s hard-coded into the React components. Let’s modify it to fetch some data using Relay.

Open up the file called Newsfeed.tsx. (All of the components in the tutorial are in src/components.) In it you should see a <Newsfeed> component where the data is hard-coded:

export default function Newsfeed() {
  const story = {
    title: "Placeholder Story",
    summary:
      "Placeholder data, to be replaced with data fetched via GraphQL",
    poster: {
      name: "Placeholder Person",
      profilePicture: {
        url: "/assets/cat_avatar.png",
      },
    },
    thumbnail: {
      url: "/assets/placeholder.jpeg",
    },
  };
  return (
    <div className="newsfeed">
      <Story story={story} />
    </div>
  );
}

We’re going to replace this placeholder data with data fetched from the server. First we need to define a GraphQL query. Add the following declaration above the Newsfeed component:

import { graphql } from 'relay-runtime';

// color1
const NewsfeedQuery = graphql`
  // color2
  query NewsfeedQuery {
    topStory {
      // color3
      title
      // color3
      summary
      // color4
      poster {
        name
        profilePicture {
          url
        }
      }
      thumbnail {
        url
      }
    }
  }
`;

Let’s break this down:

• To embed GraphQL within JavaScript, we put a string literal marked with the `graphql``` tag. This tag allows the Relay compiler to find and compile the GraphQL within a JavaScript codebase.
• Our GraphQL string consists of a query declaration with the keyword query and then a query name. The query name must be globally unique and end with Query.
• Inside the query declaration are fields, which specify what information to query for*:*
  • Some fields are scalar fields that retrieve a string, number, or other unit of information.
  • Other fields are edges that let us traverse from one node in the graph to another. When a field is an edge, it’s followed by another block { } containing fields for the node at the other end of the edge. Here, the poster field is an edge that goes from a Story to a Person who posted it. Once we’ve traversed to the Person, we can include fields about the Person such as their name.

This illustrates the part of the graph that this query is asking for:

Now that we’ve defined the query, we need to do two things.

1. Run the Relay compiler so that it knows about the new Graphql query. (npm run relay)
2. Modify our React component to fetch it and to use the data returned by the server.

If you open package.json you will find the script relay is hooked up to run the Relay compiler. This is what npm run relay does. Once the compiler successfully updates/generated the new compiled query you will be able to find it in the __generated__ folder under src/components/ as NewsfeedQuery.graphql.ts.

Next, turn back to the Newsfeed component and start by deleting the placeholder data. Then, replace it with this:

import { useLazyLoadQuery } from "react-relay";

export default function Newsfeed({}) {
  const data = useLazyLoadQuery(
    // color1
    NewsfeedQuery,
    // color2
    {},
  );
  const story = data.topStory;
  // As before:
  return (
    <div className="newsfeed">
      <Story story={story} />
    </div>
  );
}

The useLazyLoadQuery hook fetches and returns the data. It takes two arguments:

• The GraphQL query that we defined before.
• Variables that are passed to the server with the query. This query doesn’t declare any variables, so it’s an empty object.

The object that useLazyLoadQuery returns has the same shape as the query. For instance, if printed in JSON format it might look like this:

{
  topStory: {
    title: "Local Yak Named Yak of the Year",
    summary: "The annual Yak of the Year awards ceremony ...",
    poster: {
      name: "Baller Bovine Board",
      profilePicture: {
        url: '/images/baller_bovine_board.jpg',
      },
    },
    thumbnail: {
      url: '/images/max_the_yak.jpg',
    }
  }
}

Notice that each field selected by the GraphQL query corresponds to a property in the JSON response.

At this point, you should see a story fetched from the server:

:::note
The server's responses are artificially slowed down to make loading states perceptible, which will come in handy when we add more interactivity to the app. If you want to remove the delay, open server/index.js and remove the call to sleep().
:::

The useLazyLoadQuery hook fetches the data when the component is first rendered. Relay also has APIs for pre-fetching the data before your app has even loaded — these are covered later. In any case, Relay uses Suspense to show a loading indicator until the data is available.

This is Relay in its most basic form: fetching the results of a GraphQL query when a component is rendered. As the tutorial progresses, we’ll see how Relay’s features fit together to make your app more maintainable — starting with a look at how Relay generates TypeScript types corresponding to each query.

Deep dive: Suspense for Data Loading

Suspense is a new API in React that lets React wait while data is loaded before it renders components that need that data. When a component needs to load data before rendering, React shows a loading indicator. You control the loading indicator's location and style using a special component called Suspense.

Right now, there's a Suspense component inside App.tsx, which is what shows the spinner while useLazyLoadQuery is loading data.

We'll look at Suspense in more detail in later sections when we add some more interactivity to the app.

Deep dive: Queries are Static

All of the GraphQL strings in a Relay app are pre-processed by the Relay compiler and removed from the resulting bundled code. This means you can’t construct GraphQL queries at runtime — they have to be static string literals so that they’re known at compile time. But it comes with major advantages.

First, it allows Relay to generate type definitions for the results of the query, making your code more type-safe.

Second, Relay replaces the GraphQL string literal with an object that tells Relay what to do. This is much faster than using the GraphQL strings directly at runtime.

Also, Relay’s compiler can be configured to save queries to the server when you build your app, so that at runtime the client need only send a query ID instead of the query itself. This saves bundle size and network bandwidth, and can prevent attackers from writing malicious queries since only those your app was built with need be available.

So when you have a GraphQL tagged string literal in your program...

const MyQuery = graphql`
  query MyQuery {
    viewer {
      name
    }
  }
`;

... the JavaScript variable MyQuery is actually assigned to an object that looks something like this:

const MyQuery = {
  kind: "query",
  selections: [
    {
      name: "viewer",
      kind: "LinkedField",
      selections: [
        name: "name",
        kind: "ScalarField",
      ],
    }
  ]
};

along with various other properties and information. These data structures are carefully designed to allow the JIT to run Relay’s payload processing code very quickly. If you’re curious, you can use the Relay Compiler Explorer to play with it.

Relay and the Type System Copy Chapter

You might notice that TypeScript reports an error with this code as we’ve written it:

const story = data.topStory;
                   ^^^^^^^^
Property 'topStory' does not exist on type 'unknown'

To fix this, we need to annotate the call to useLazyLoadQuery with types that Relay generates. That way, TypeScript will know what type data should have based on the fields we’ve selected in our query. Add the following:

// change-line
import type {NewsfeedQuery as NewsfeedQueryType} from './__generated__/NewsfeedQuery.graphql';

function Newsfeed({}) {
  const data = useLazyLoadQuery
  // change-line
  <NewsfeedQueryType>
  (NewsfeedQuery, {});
  ...
}

If we look inside __generated__/NewsfeedQuery.graphql we’ll see the following type definition — with the annotation we’ve just added, TypeScript knows that data should have this type:

export type NewsfeedQuery$data = {
  readonly topStory: {
    readonly poster: {
      readonly name: string | null;
      readonly profilePicture: {
        readonly url: string;
      } | null;
    };
    readonly summary: string | null;
    readonly thumbnail: {
      readonly url: string;
    } | null;
    readonly title: string;
  } | null;
};

The Relay compiler generates TypeScript types corresponding to every piece of GraphQL that you have in your app within a graphql``` literal. As long as npm run dev` is running, the Relay compiler will automatically regenerate these files whenever you save one of your JavaScript source files, so you don’t need to refresh anything to keep them up to date.

Using Relay’s generated types makes your app safer and more maintainable. In addition to TypeScript, Relay supports the Flow type system if you want to use that instead. When using Flow, the extra annotation on useLazyLoadQuery is not needed, because Flow directly understands the contents of the `graphql``` tagged literal.

We’ll revisit types throughout this tutorial. But next, we'll look at an even more important way that Relay helps us with maintainability.

Summary Copy Chapter

Queries are the foundation of fetching GraphQL data. We’ve seen:

• How to define a GraphQL query within our app using the `graphql``` tagged literal.
• How to use the useLazyLoadQuery hook to fetch the results of a query when a component renders.
• How to import Relay's generated types for type safety.

In the next section, we’ll look at Fragments, one of the most core and distinctive aspects of Relay. Fragments let each individual component define its own data requirements, while retaining the performance advantages of issuing a single query to the server.

Tutorial Queries 2 (`website/docs/tutorial/queries-2.mdx`) Copy Section

Queries for Interactions

We’ve seen how fragments let us specify data requirements in each component, yet at runtime perform only a single query for an entire screen. Here we’ll look at a situation where we want a second query on the same screen. This will also let us explore some more features of GraphQL queries.

• We’ll build a hovercard that shows more details about the poster of a story when you hover over their name.
• The hovercard will use a second query to fetch additional information that’s only needed if the user hovers.
• We’ll use query variables to tell the server which person we’d like more details about.
• We’ll see how to improve performance with preloaded queries.

After covering these topics, we’ll return to look at some more advanced features of Fragments.

In this section we’ll add a hovercard to PosterByline so that you can see more details about the poster of a story by hovering over their name.

Deep dive: When to use a secondary query

We've mentioned before that Relay is designed to help you fetch all of your data requirements for an entire screen up-front. But we can generalize this and say that it's a user interaction that should have at most one query. Navigating to another screen is just one common type of user interaction.

Within a screen, some interactions may disclose additional data from what was shown initially. If an interaction is performed relatively rarely, but needs a significant amount of additional data, it can be smart to fetch that additional data in a second query, performed when the interaction happens, rather than up-front when the screen is first loaded. This makes that initial load faster and less expensive.

There are also some interactions where the amount of data fetched is indefinite — e.g., a hovercard within a hovercard — and not feasible to know statically.

If data is lower-priority and should be loaded after the main data has loaded, but should pop in automatically without further user input, Relay has a feature called a deferred fragment for that. We'll cover it later.

We’ve already prepared a hovercard component that you can put to use. However, it has been in a directory called future in order to avoid compilation errors since it uses ImageFragment. Now that we’re at this stage of the tutorial, you can move the modules in future into src/components:

mv future/* src/components

Now, if you did the exercise to make PosterByline use fragments, the PosterByline component should look something like this:

export default function PosterByline({ poster }: Props): React.ReactElement {
  const data = useFragment(PosterBylineFragment, poster);
  return (
    <div className="byline">
      <Image image={data.profilePicture} width={60} height={60} className="byline__image" />
      <div className="byline__name">{data.name}</div>
    </div>
  );
}

To use the hovercard component, you can make the following changes:

// change-line
import Hovercard from './Hovercard';
// change-line
import PosterDetailsHovercardContents from './PosterDetailsHovercardContents';
// change-line
const {useRef} = React;

...

export default function PosterByline({ poster }: Props): React.ReactElement {
  const data = useFragment(PosterBylineFragment, poster);
  // change-line
  const hoverRef = useRef(null);
  return (
    <div
      // change-line
      ref={hoverRef}
      className="byline">
      <Image image={data.profilePicture} width={60} height={60} className="byline__image" />
      <div className="byline__name">{data.name}</div>
      // change
      <Hovercard targetRef={hoverRef}>
        <PosterDetailsHovercardContents />
      </Hovercard>
      // end-change
    </div>
  );
}

You should now see that whenever you hover over someone’s name, you get a hovercard with more information. If you look inside PosterDetailsHovercardContents.tsx, you’ll find that it performs a second query with useLazyLoadQuery to fetch additional information when that component is mounted.

There’s just one problem: it always shows the same person's information, no matter which poster you hover over!

Query Variables Copy Chapter

We need to tell the server which information we want more information about. GraphQL lets us define query variables that can be passed as arguments to specific fields. These arguments are then available on the server.

In the previous section, we saw how a field can accept arguments, but the argument values were hard-coded, e.g. url(width: 200, height: 200). With query variables, we can determine these values at runtime. They’re passed from the client to the server alongside the query itself. GraphQL variables always begin with a $ dollar sign.

Take a look inside PosterDetailsHovercardContents.tsx: you should see a query like this one:

const PosterDetailsHovercardContentsQuery = graphql`
  query PosterDetailsHovercardContentsQuery {
    // color1
    node(id: "1") {
      // color2
      ... on Actor @alias(as: "actor") {
        ...PosterDetailsHovercardContentsBodyFragment
      }
    }
  }
`;

The node field is a top-level field defined in our schema that lets us fetch any graph node given its unique ID. It takes the ID as an argument, which is currently hard-coded. In this exercise, we’ll be replacing this hard-coded ID with a variable supplied by our UI state.

The funny-looking ... on Actor is a type refinement. We’ll look at these in more detail in the next section and can ignore it for now. In brief, since we could supply any ID at all to the node field, there’s no way to know statically what type of node we’d be selecting. The type refinement specifies what type we expect, allowing us to use fields from the Actor type. Because the node might not actually be an Actor at runtime, we tag the refinement with @alias(as: "actor"), which exposes it as a nullable actor field on node — that's why the component below reads data.node?.actor.

Within that, we simply spread a fragment that contains the fields we want to show — about which more later. For now, here are the steps to take to replace this hard-coded ID with the ID of the poster we’re hovering over:

Step 1 — define a query variable Copy Section

First we need to edit our query to declare that it accepts a query variable. Here’s the change:

const PosterDetailsHovercardContentsQuery = graphql`
  query PosterDetailsHovercardContentsQuery(
    // change-line
    $posterID: ID!
  ) {
    node(id: "1") {
      ... on Actor @alias(as: "actor") {
        ...PosterDetailsHovercardContentsBodyFragment
      }
    }
  }
`;

• The variable name is $posterID. This is the symbol we’ll use within the rest of the GraphQL query to refer to the value passed in from the UI.
• Variables have a type — in this case ID!. The ID type is a synonym for String that is used for node IDs to help distinguish them from other strings. The ! on ID! means that field is non-nullable. In GraphQL, fields are normally nullable and non-nullability is the exception.

Step 2 — pass the variable in as a field argument Copy Section

Now we replace the hard-coded "1" with our new variable:

const PosterDetailsHovercardContentsQuery = graphql`
  query PosterDetailsHovercardContentsQuery($posterID: ID!) {
    node(
      // change-line
      id: $posterID
    ) {
    ... on Actor @alias(as: "actor") {
      ...PosterDetailsHovercardContentsBodyFragment
      }
    }
  }
`;

:::note
You can use query variables not only as field arguments, but as arguments to fragments.
:::

Step 3 — provide the argument value to useLazyLoadQuery Copy Section

Now we need to pass in the actual value from our UI at runtime. The useLazyLoadQuery hook’s second argument is an object with variable values. We’ll add a new prop to our component and pass its value in there:

export default function PosterDetailsHovercardContents({
  // change-line
  posterID,
}: {
  // change-line
  posterID: string;
}): React.ReactElement {
  const data = useLazyLoadQuery<QueryType>(
    PosterDetailsHovercardContentsQuery,
    // change-line
    {posterID},
  );
  return <PosterDetailsHovercardContentsBody poster={data.node?.actor} />;
}

Step 4 — pass the ID in from the parent component Copy Section

Now we need to supply the posterID prop from the hovercard’s parent component, which is PosterByline. Head over to that file and add id to its fragment — then pass the ID in as a prop:

const PosterBylineFragment = graphql`
  fragment PosterBylineFragment on Actor {
    // change-line
    id
    ...
  }
`;

export default function PosterByline({ poster }: Props): React.ReactElement {
  ...
  return (
   ...
    <PosterDetailsHovercardContents
      // change-line
      posterID={data.id}
    />
   ...
  );
}

At this point, the hovercard should show the appropriate information for each poster that we hover over.

If you use the Network inspector in your browser, you should be able to find that the variable value is being passed alongside the query:

You may also notice that this request is made only the first time you hover over a particular poster. Relay caches the results of the query and re-uses them after that, until eventually removing the cached data if it hasn’t been used recently.

Deep dive: Caching and the Relay Store

In contrast to most other systems, Relay’s caching is not based on queries, but on graph nodes. Relay maintains a local cache of all the nodes it has fetched called the Relay Store. Each node in the Store is identified and retrieved by its ID. If two queries ask for the same information, as identified by node IDs, then the second query will be fulfilled using the cached information retrieved for the first query, and not be fetched. Make sure to configure missing field handlers to take advantage of this caching behavior.

Relay will garbage-collect nodes from the Store if they aren’t “reachable” from any queries that are used, or have been recently used, by any mounted components.

Deep dive: Why GraphQL Needs a Syntax for Variables

You might be wondering why GraphQL even has the concept of variables, instead of just interpolating the value of the variables into the query string. Well, as mentioned before, the text of the GraphQL query string isn’t available at runtime, because Relay replaces it with a data structure that is more efficient. You can also configure Relay to use prepared queries, where the compiler uploads each query to the server at build time and assigns it an ID — in that case, at runtime, Relay is just telling the server “Give me query #1337”, so string interpolation isn't possible and therefore the variables have to come out of band. Even when the query string is available, passing variable values separately eliminates any issues with serializing arbitrary values and escaping strings, above what is required with any HTTP request.

Preloaded Queries Copy Chapter

This example app is very simple, so performance isn't an issue. (In fact, the server is artificially slowed down in order to make loading states perceptible.) However, one of Relay's main concerns is to make performance as fast as possible in real apps.

Right now, the hovercard uses the useLazyLoadQuery hook, which fetches the query when the component is rendered. That means the timeline looks something like this:

Ideally, we should start the network fetch as early as possible, but here we don't start it until React is finished rendering. This timeline could look even worse if we used React.lazy to load the code for the hovercard component itself when the interaction happened. In that case, it would look like this:

Notice how we’re waiting around before we even start fetching the GraphQL query. It would be better if the query fetch began before the React component even rendered, right at the beginning in the mouse event handler itself. Then the timeline would look like this:

When the user interacts, we should immediately start fetching the query we need, while also beginning to render the component (fetching its code first if needed). Once both of these async processes are complete, we can render the component with the data available and show it to the user.

Relay provides a feature called preloaded queries that let us do this.

Let’s modify the hovercard to use preloaded queries.

Step 1 — change useLazyLoadQuery to usePreloadedQuery Copy Section

As a reminder, this is the PosterDetailsHovercardContents component that currently fetches the data lazily:

export default function PosterDetailsHovercardContents({
  posterID,
}: {
  posterID: string;
}): React.ReactElement {
  const data = useLazyLoadQuery<QueryType>(
    PosterDetailsHovercardContentsQuery,
    {posterID},
  );
  return <PosterDetailsHovercardContentsBody poster={data.node?.actor} />;
}

It calls useLazyLoadQuery which accepts variables as its second argument. We want to change this to usePreloadedQuery. However, with preloaded queries, the variables are actually determined when the query is fetched, which will be before this component is even rendered. So instead of variables, this hook takes a query reference that contains the information it needs to retrieve the results of the query. The query reference will be created when we fetch the query in Step 2.

Change the component as follows:

import {usePreloadedQuery} from 'react-relay';
import type {PreloadedQuery} from 'react-relay';
import type {PosterDetailsHovercardContentsQuery as QueryType} from './__generated__/PosterDetailsHovercardContentsQuery.graphql';

export default function PosterDetailsHovercardContents({
  // change-line
  queryRef,
}: {
  // change-line
  queryRef: PreloadedQuery<QueryType>,
}): React.ReactElement {
  // change-line
  const data = usePreloadedQuery(
    PosterDetailsHovercardContentsQuery,
    // change-line
    queryRef,
  );
  ...
}

:::note
We’ll be modifying the parent component, PosterByline, to have it initiate the PosterDetailsHovercardContentsQuery query. Since it needs a reference to the query, the query needs to be exported:

export const PosterDetailsHovercardContentsQuery = graphql`...

:::

Step 2 — Call useQueryLoader in the parent component Copy Section

Now that PosterDetailsHovercardContents expects a query ref, we need to create that query ref and pass it down from the parent component, which is PosterByline. We create the query ref using a hook called useQueryLoader. This hook also returns a function that we call in our event handler to trigger the query fetch.

import {useQueryLoader} from 'react-relay';
import type {PosterDetailsHovercardContentsQuery as HovercardQueryType} from './__generated__/PosterDetailsHovercardContentsQuery.graphql';
import {PosterDetailsHovercardContentsQuery} from './PosterDetailsHovercardContents';

export default function PosterByline({ poster }: Props): React.ReactElement {
  ...
  // change
  const [
    hovercardQueryRef,
    loadHovercardQuery,
  ] = useQueryLoader<HovercardQueryType>(PosterDetailsHovercardContentsQuery);
  // end-change
  return (
   ...
    <PosterDetailsHovercardContents
      // change-line
      queryRef={hovercardQueryRef}
    />
   ...
  );
}

The useQueryLoader hook returns two things we need:

• The query ref is an opaque piece of information that usePreloadedQuery will use to retrieve the result of the query.
• loadHovercardQuery is a function that will initiate the request.

Step 3 — Fetch the query in the event handler Copy Section

Finally, we need to call loadHovercardQuery in an event handler that happens when the card is shown. Luckily the Hovercard component has a onBeginHover event that we can use:

export default function PosterByline({ poster }: Props): React.ReactElement {
  ...
  const [
    hovercardQueryRef,
    loadHovercardQuery,
  ] = useQueryLoader<HovercardQueryType>(PosterDetailsHovercardContentsQuery);
  // change
  function onBeginHover() {
    loadHovercardQuery({posterID: data.id});
  }
  // end-change
  return (
    <div className="byline">
      ...
      <Hovercard
        // change-line
        onBeginHover={onBeginHover}
        targetRef={hoverRef}>
        <PosterDetailsHovercardContents queryRef={hovercardQueryRef} />
      </Hovercard>
    </div>
  );
}

Note that the query variables are now passed in here where we initiate the request.

At this point, you should see the same behavior as before, but now it will be a little bit faster since Relay can get the query started earlier.

:::tip
Although we introduced queries using useLazyLoadQuery for simplicity, preloaded queries are always the preferred way to use queries in Relay because they can significantly improve performance in the real world. With the appropriate integrations with your server and router system, you can even preload the main query for a webpage on the server side before you’ve even downloaded or run any client code.
:::

Summary Copy Chapter

• Although all of the data initially shown on a screen should be combined into one query, user interactions needing further information can be handled with secondary queries.
• Query variables let you pass information to the server along with your query.
• Query variables are used by passing them into field arguments.
• Preloaded queries are always the best way to go. For user interaction queries, initiate the fetch in the event handler. For the initial query for your screen, initiate the fetch as early as possible in your specific routing system. Use lazy-loaded queries only for quick prototyping, or not at all.

Next we'll briefly look at a way to enhance the hovercard by handling different types of posters differently. After that, we'll see how to handle situations where information that's part of the initial query also needs to be updated and refetched with different variables.

Tutorial Refetchable Fragments (`website/docs/tutorial/refetchable-fragments.mdx`) Copy Section

Refetchable Fragments

In this section, we'll look at how to fetch different data in response to user input.

• We'll build a filterable friends list.
• We'll see how to refetch only the necessary data, not an entire query.

Since Relay encourages you to fetch all of your data in one big query, what happens when you need to refetch some data with different variables?

For example, suppose you were building a filterable list. You would need to fetch new search results when the search input changed.

One way to approach this would be to use a separate, secondary query to fetch the list, much like we did to fetch the hovercard earlier. Then we could change the query variables and refetch the query when the input changed.

However, this isn't optimal, because it needlessly uses a second query to fetch the initial list, before any user input occurs. The hovercard only appeared in response to a user interaction, but if the filterable list is visible and ready to be filtered, we might as well get its initial contents as part of our big query.

On the other hand, we don't want to refetch the entire big query whenever the input changes. Not only would this mean retrieving a large amount of data unnecessarily, it could disrupt other parts of the UI. If certain data unrelated to the filterable list has changed on the server, it would appear to randomly change when the query was refetched. Besides, this would mean threading the user input up to the top of the React tree where the query lives, which would not scale very well.

To address these issues, Relay provides refetchable fragments. These are fragments that can be refetched with new variables, separately from the rest of the query that they get spread into. They allow us to change a fragment’s arguments and fetch new data for the new argument values, just as we can fetch an entire query with new query variables.

But fragments are just that, fragments — they aren’t queries and can’t be fetched without being spread into a query and read out from the query results. So how do refetchable fragments actually work? The answer is that the Relay compiler generates a new, separate query just to refetch the fragment. The data is retrieved initially as part of whatever larger query the fragment is spread into, but then when it’s refetched, the new synthetic query is used.

To try this out, let's add a sidebar to the page with a filterable contacts list. After all, it wouldn't feel like a properly cozy newsfeed app without the ability to contact people.

We've already prepared a Sidebar component, you just need to drop it into App.tsx:

// change-line
import Sidebar from './Sidebar';

export default function App(): React.ReactElement {
  return (
    <RelayEnvironment>
      <React.Suspense fallback={<LoadingSpinner />}>
        <div className="app">
          <Newsfeed />
          // change-line
          <Sidebar />
        </div>
      </React.Suspense>
    </RelayEnvironment>
  );
}

You should now see a sidebar with a list of people at the top.

Have a look at ContactsList.tsx and you’ll find this fragment, which is what selects the list of contacts:

const ContactsListFragment = graphql`
  fragment ContactsListFragment on Viewer {
    contacts {
      id
      ...ContactRowFragment
    }
  }
`;

As it happens, the contacts field accepts a search argument that filters the list. You can try it out by changing contacts in this fragment to contacts(search: "S"). If you run npm run relay and refresh the page, you should see only those contacts that have the letter S in them.

Our goal, then, will be to hook up a search input so that, when the input changes, we refetch just this fragment with a new value for that search argument.

:::tip
As an optional exercise, try combining the queries of Sidebar and Newsfeed into a single query. There is no need for Sidebar to have its own query separate from Newsfeed; in a real app they would both have fragments and the entire screen would have only a single query. We built it with a separate query to simplify the early examples in the tutorial.
:::

Step 1 — Add a fragment argument Copy Section

First we need to make this fragment accept an argument. With refetchable fragments, fragment arguments become query variables for the refetch query that Relay generates. (They also work like regular fragment arguments, so the parent query can pass in an initial value for the argument.)

const ContactsListFragment = graphql`
  fragment ContactsListFragment on Viewer
    // change
    @argumentDefinitions(
      search: {type: "String", defaultValue: null}
    )
    // end-change
  {
    contacts {
      id
      ...ContactRowFragment
    }
  }
`;

Step 2 — Pass the fragment argument as a field argument Copy Section

Pass the fragment argument in as an argument to the contacts field.

const ContactsListFragment = graphql`
  fragment ContactsListFragment on Viewer
    @argumentDefinitions(
      search: {type: "String", defaultValue: null}
    )
  {
    // change-line
    contacts(search: $search) {
      id
      ...ContactRowFragment
    }
  }
`;

Remember, the first search here is the name of the argument to contacts, while the second $search is the variable created by our fragment argument.

Step 3 — Add the @refetchable directive Copy Section

Next we'll add a @refetchable directive. This tells Relay to generate the extra query for refetching it. You have to specify the name of the generated query — it's a good idea to base it on the name of the fragment.

const ContactsListFragment = graphql`
  fragment ContactsListFragment on Viewer
    // change-line
    @refetchable(queryName: "ContactsListRefetchQuery")
    @argumentDefinitions(
      search: {type: "String", defaultValue: null}
    )
  {
     // ...
  }
`;

Step 4 — Add the search input Copy Section

Now we need to actually hook this up to our UI. Take a look at the ContactsList component:

export default function ContactsList({ viewer }: Props) {
  const data = useFragment(ContactsListFragment, viewer);
  return (
    <Card dim={true}>
      <h3>Contacts</h3>
      {data.contacts.map(contact =>
        <ContactRow key={contact.id} contact={contact} />
      )}
    </Card>
  );
}

First we need to add a search field.

// change-line
import SearchInput from './SearchInput';

// change-line
const {useState} = React;

function ContactsList({viewer}) {
  const data = useFragment(ContactsListFragment, viewer);
  // change-line
  const [searchString, setSearchString] = useState('');
  // change
  const onSearchStringChanged = (value: string) => {
    setSearchString(value);
  };
  // end-change
  return (
    <Card dim={true}>
      <h3>Contacts</h3>
      // change
      <SearchInput
        value={searchString}
        onChange={onSearchStringChanged}
      />
      // end-change
      {data.contacts.map(contact =>
        <ContactRow key={contact.id} contact={contact} />
      )}
    </Card>
  );
}

Step 5 — Call useRefetchableFragment Copy Section

Now to refetch the fragment when the string changes, we change useFragment to useRefetchableFragment. This hook returns a refetch function which will refetch the fragment with new variables which we provide as an argument.

// change-line
import {useRefetchableFragment} from 'react-relay';

function ContactsList({viewer}) {
  // change-line
  const [data, refetch] = useRefetchableFragment(ContactsListFragment, viewer);
  const [searchString, setSearchString] = useState('');
  const onSearchStringChanged = (value) => {
    setSearchString(value);
    // change-line
    refetch({search: value});
  };
  return (
    // ...
  );
}

You’ll notice that Relay gives us a callback for refetching, rather than accepting the new state variables as an argument to the hook and refetching when it is re-rendered with a different value. This means that the fetch begins as soon as the event takes place, saving some time versus waiting until React finishes re-rendering — the same principle we saw before with preloaded queries. It also gives us more control, for example if we wanted to debounce the refetch.

Step 6 — Control loading with useTransition Copy Section

At this point, when the fragment is refreshed, Relay uses Suspense while the new data is loading, so the entire component is replaced with a spinner! This makes the UI fairly unusable. We would rather just keep the current data on screen until the new data is available.

The way Suspense normally works is this: When a component is missing data that it needs to render (as our component does after we refetch), it tells React to wait. When this happens, React finds the nearest Suspense component in the tree. It then replaces everything under that component with a "fallback" loading indicator.

This makes sense when initially loading a screen, but in this instance there's no reason to hide the existing UI and replace it with a spinner. While React is waiting, it can simply continue showing what's already there.

To achieve this, we can mark the refetch as a transition. Transitions are React state updates that do not need to be immediately responded to — React can wait until the data is available.

Transitions are marked by wrapping the state change in a call to a function provided by the useTransition hook. This is what the code will look like:

// change-line
const {useState, useTransition} = React;

function ContactsList({viewer}) {
  // change-line
  const [isPending, startTransition] = useTransition();
  const [searchString, setSearchString] = useState('');
  const [data, refetch] = useRefetchableFragment(ContactsListFragment, viewer);
  const onSearchStringChanged = (value) => {
    setSearchString(value);
    // change
    startTransition(() => {
      refetch({search: value});
    });
    // end-change
  };
  return (
    <Card dim={true}>
      <h3>Contacts</h3>
      <SearchInput
        value={searchString}
        onChange={onSearchStringChanged}
        // change-line
        isPending={isPending}
      />
      {data.contacts.map(contact =>
        <ContactRow key={contact.id} contact={contact} />
      )}
    </Card>
  );
}

While React is waiting for the new data, instead of using a Suspense fallback, React re-renders the component with the isPending flag set to true.

We simply pass the isPending flag to SearchInput (which causes it to show a spinner) while the refetch is happening. Meanwhile, by placing setSearchString outside of the transition but refetch within it, we tell React to immediately update the search input.

We should now be able to search the contacts list with a nice user experience, showing a spinner but keeping the previous data visible while loading.

Deep dive: What fragments can be refetched?

To refetch fragments, Relay has to know how to generate a query that lets it refetch just the information from the fragment. That’s only possible for fragments that meet certain requirements.

You might imagine that we could, if nothing else, re-run the original query that the fragment was spread into. However, GraphQL doesn’t guarantee that the same query will return the same results at different times. For instance, imagine you had a GraphQL field that returned the top trending posts across the site:

query MyQuery {
  topTrendingPosts {
    title
    summary
    date
    poster {
     ...PosterFragment
    }
  }
}

If you wanted to refresh just PosterFragment from this query, it wouldn’t work to construct a query like this:

query MyQuery {
  topTrendingPosts {
    poster {
     ...PosterFragment
    }
  }
}

... because the top trending post could be a different post by the time you refresh it!

Relay needs a way of identifying the specific node in the graph that the fragment ends up on, even if it can no longer be reached by the same path that the original query uses. If the node has a unique and stable ID, then we can just have a convention for querying for “the graph node with some specific ID” like so:

query RefetchQuery {
  node(id: "abcdef") {
    ...PosterFragment
  }
}

In fact, this is exactly the convention that Relay uses. It expects your server to implement a top-level field called node that takes an ID and gives you the graph node with that ID. (We saw node earlier with the hovercard example — there it was used to fetch a specific person given their ID using a secondary query.)

Not every graph node has a stable ID — some are ephemeral. To be used with node, your schema has to declare that its type implements an interface called Node:

type Person implements Node {
  id: ID!
  ...
}

The Node interface simply says it has an ID, but more importantly indicates by convention that that ID is stable and unique:

interface Node {
  id: ID!
}

import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';

Besides fragments on types that implement Node, you can also refetch fragments that are on Viewer (since the viewer is assumed to be stable throughout a session) and that are at the top level of a query (since there’s no field above them that could change identity).

Summary Copy Chapter

Refetchable fragments let us efficiently update specific parts of the UI in response to user input, while initializing them as part of the same query that we use for the entire screen.

Relay's pagination features are built on refetchable fragments, too. We'll explore those next.

Api Reference Entrypoint Apis Entrypoint Container (`website/docs/api-reference/entrypoint-apis/entrypoint-container.mdx`) Copy Section

id: entrypoint-container
title: EntryPointContainer
slug: /api-reference/entrypoint-container/
keywords:

• entrypoint
• container
• root

import DocsRating from '@site/src/core/DocsRating';
import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';

`EntryPointContainer` Copy Chapter

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

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.

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>
          </>
        )
      }
    </>
  );
}