Relay-style GraphQL

An example Relay component

function IssueSummary(props: {
  issue: IssueSummaryFragment$key;
}) {
  const issue = useFragment(
    graphql`
      fragment IssueSummaryFragment on Issue {
        title
        body
      }
    `,
    props.issue
  );

  return (
    <li>
      <h1>{issue.title}</h1>
      <div>{issue.body}</div>
    </li>
  );
}

function IssueSummary(props: {
  issue: IssueSummaryFragment$key;
}) {
  const issue = useFragment(
    graphql`
      fragment IssueSummaryFragment on Issue {
        title
        body
      }
    `,
    props.issue
  );

  return (
    <li>
      <h1>{issue.title}</h1>
      <div>{issue.body}</div>
    </li>
  );
}

The parent component would then spread that fragment in its fragment and render the child component:

1function Issues(props: {
2  repository: IssuesFragment$key | null;
3}) {
4  const data = useFragment(
5    graphql`
6      fragment IssuesFragment on Repository {
7        issues(first: 1) {
8          nodes {
9            __id
10            ...IssueSummaryFragment
11        }
12      }
13    `,
14    props.repository
15  );
16
17  return (
18    <ul className={styles.issues}>
19      {data?.issues.nodes?.map((issue) => {
20        if (issue == null) {
21          return null;
22        }
23        return <IssueSummary key={issue.__id} issue={issue} />;
24      })}
25    </ul>
26  );
27}
28

1function Issues(props: {
2  repository: IssuesFragment$key | null;
3}) {
4  const data = useFragment(
5    graphql`
6      fragment IssuesFragment on Repository {
7        issues(first: 1) {
8          nodes {
9            __id
10            ...IssueSummaryFragment
11        }
12      }
13    `,
14    props.repository
15  );
16
17  return (
18    <ul className={styles.issues}>
19      {data?.issues.nodes?.map((issue) => {
20        if (issue == null) {
21          return null;
22        }
23        return <IssueSummary key={issue.__id} issue={issue} />;
24      })}
25    </ul>
26  );
27}
28

A top-level component will make a query and (either directly or transitively) spread all the fragments of all its descendent components:

1function MainView(props: {
2  queryRef: PreloadedQuery<MainViewQuery>;
3}) {
4  const data = usePreloadedQuery(
5    graphql`
6      query MainViewQuery($owner: String!, $name: String!) {
7        repository(owner: $owner, name: $name) {
8          owner {
9            login
10          }
11          name
12          ...IssuesFragment
13        }
14      }
15    `,
16    props.queryRef
17  );
18
19  // ...
20}

1function MainView(props: {
2  queryRef: PreloadedQuery<MainViewQuery>;
3}) {
4  const data = usePreloadedQuery(
5    graphql`
6      query MainViewQuery($owner: String!, $name: String!) {
7        repository(owner: $owner, name: $name) {
8          owner {
9            login
10          }
11          name
12          ...IssuesFragment
13        }
14      }
15    `,
16    props.queryRef
17  );
18
19  // ...
20}

The result is the same as if you had manually written this top-level query into a MainViewQuery.graphql file, like so:

1query MainViewQuery($owner: String!, $name: String!) {
2  repository(owner: $owner, name: $name) {
3    owner {
4      login
5    }
6    name
7    issues(first: 1) {
8      edges {
9        __id
10        node {
11          title
12          number
13          author {
14            login
15          }
16        }
17      }
18    }
19  }
20}

1query MainViewQuery($owner: String!, $name: String!) {
2  repository(owner: $owner, name: $name) {
3    owner {
4      login
5    }
6    name
7    issues(first: 1) {
8      edges {
9        __id
10        node {
11          title
12          number
13          author {
14            login
15          }
16        }
17      }
18    }
19  }
20}

But, instead of writing this query by hand, a Relay-style GraphQL library will compile your collocated fragments into the same query, giving you many benefits:

Benefit #1: Preventing over-fetching

Relay-style GraphQL code has perfect data efficiency, never fetching data it doesn’t need.

REST APIs can theoretically fetch exactly the data your UI needs, or they can have flexible query parameters to filter your requested data², but in practice they have to over-fetch to serve multiple use cases in your UI. Data provided by REST APIs is usually an ever-increasing superset of what is actually needed by the UI, as pruning of the data is a solvable but often neglected problem.

GraphQL improved on this by allowing the UI author to always request exactly what data they are looking for, in theory always achieving perfect data-fetching efficiency and never over-fetching. The problem arises when you share GraphQL queries/fragments across multiple components: static analysis can’t tell you when a field in a .graphql file is unused and therefore safe to remove³.

Fragment collocation in Relay-style GraphQL solves this problem: if you remove a field from the component’s fragment, or if you just remove the component, and no other component references that field, it will be removed from your query without any action on your part. Relay implements tooling to facilitate all this:

• Data Masking: Your component can only see what it puts in its fragment. Your component gets a key via its props but that key isn’t usable until fed through something like useFragment, and the data returned by useFragment only contains the data defined in the component’s fragment.
• Lint rules that prevent you from doing anything that might result in bad data fetching/passing practices, e.g. adding a field to your fragment only to pass it into a child component, spreading fragments that you don’t use directly, etc.
• TypeScript typing to prevent rendering a component without spreading its fragment.
• Etc.

Benefit #2: Preventing under-fetching

Relay-style GraphQL code doesn’t have bugs where components need data that was never queried.

Without fragment collocation it’s possible to write a React component that doesn’t always get the data it depends on. For example, let’s say you have a component that takes a User object that has firstName and lastName fields. Your component knows that these fields are nullable and has appropriate null checking, but it can’t guarantee that all the queries that use your component include both fields. This can lead to bugs at runtime where your component unexpectedly returns null. UI rarely even logs this error case.

With fragment collocation you can be guaranteed that all the data your component needs will always be queried, because you can’t render the component without querying. The fields may still end up being null, but not because of bugs in your GraphQL code.

Benefit #3: Your components are easier to reason about

If your collocated fragments abide by the first principle above:

“Your component must never receive GraphQL-sourced data in its props: it should only have access to what it declares in its fragment(s)”

they will be much easier to reason about. This is my personal favorite benefit of collocated fragments, and of Relay-style GraphQL in general.

For example, take this standard React component that gets GraphQL data from a prop:

1function IssueTitle(props: { issue: { title: string|null } }) {
2  return <li>{props.issue.title}</li>;
3}

1function IssueTitle(props: { issue: { title: string|null } }) {
2  return <li>{props.issue.title}</li>;
3}

This component seems very simple but if you need any information about where this title comes from in order to render the component, you’ll have to search elsewhere. Want to use another field in your render? You’ll have to add a prop and then go find where the data is sourced so you can add the field there.

Compare it to a GraphQL component with a collocated fragment:

1function IssueTitle(props: { issue: IssueTitleFragment$key }) {
2  const issue = useFragment(
3    graphql`
4      fragment IssueTitleFragment on Issue {
5        title
6      }
7    `,
8    props.issue
9  );
10  return <p>{issue.title}</p>;
11}

1function IssueTitle(props: { issue: IssueTitleFragment$key }) {
2  const issue = useFragment(
3    graphql`
4      fragment IssueTitleFragment on Issue {
5        title
6      }
7    `,
8    props.issue
9  );
10  return <p>{issue.title}</p>;
11}

Here we can easily see that title is a field on the Issue type.

Want to see the schema documentation for it? Just mouse over the field:

Want to jump to the schema and see related fields? Cmd-click the field from here.

Want to use another field in your render? Just add it right in this component’s fragment.

You get the idea.

Benefit #4: Improved TypeScript types

If your collocated fragments abide by the second principle above:

“Component’s must never share fragments.”

they will benefit from much improved TypeScript typing.

It’s possible to work in a codebase where TypeScript typing of GraphQL data is bad. There are several ways that can happen. For example:

• Types get widened in the definition of a component prop. For example, a GraphQL type might be a union of string literals but the component’s prop widens it to string.
• The GraphQL data goes through a transform operation that doesn’t keep all the GraphQL types, and what types it does keep get demoted from something specific based on the query. For example, you query for one field but the type you use is the abstract GraphQL type that includes all the fields, all nullable, even though you didn’t query for them. In this case your editor’s autocomplete will think it potentially has access to all the fields, which is asking for trouble.
• Field types get lost through non-strict typing and vanilla JavaScript.

Even in a codebase with non-strict, non-rigorous TypeScript the typing of GraphQL in a Relay-style component will always be perfect, because your component gets its own auto-generated, custom type that is based on its fragment. The rest of the codebase doesn’t matter. And since you’re not passing GraphQL data around in props, the types never degrade.

If you don’t have a field in your fragment, your TypeScript type won’t have it, regardless of whether or not other components query for it. Your TypeScript type perfectly represents your component.

Having a custom TypeScript type for each fragment gives you other developer experience gains as well, covered later.

Benefit #5: Easily re-fetch just your component’s data

By separating your GraphQL into fragments you’re also setting yourself up to easily re-fetch just the data your component needs instead of the entire query. Relay, for example, makes it trivial to upgrade a fragment to a re-fetchable fragment, auto-generating a function that, when called, will send a query for just the data in your fragment.

Without collocated fragments you have to choose between:

• Re-fetching your entire query or
• Manually writing a function that re-fetches just what you want and manually mutating the local cache to reflect the re-fetched data.

Bonus: having globally unique IDs for items in the graph means that re-fetching data for just one component will NOT cause data inconsistencies in your UI. If your auto-generated re-fetch function has data for an item that is rendered by two different components your UI will use the fresh data in both places (using Relay’s normalized store⁴).

Benefit #6: Your component can fetch different data, depending on context

1query PreviewItemQuery($isForPreview: Boolean = true) {
2  ...ItemFragment
3}
4
5query SavedItemQuery($isForPreview: Boolean = false) {
6  ...ItemFragment
7}
8
9fragment ItemFragment on Item {
10  id @skip(if: $isForPreview)
11}

1query PreviewItemQuery($isForPreview: Boolean = true) {
2  ...ItemFragment
3}
4
5query SavedItemQuery($isForPreview: Boolean = false) {
6  ...ItemFragment
7}
8
9fragment ItemFragment on Item {
10  id @skip(if: $isForPreview)
11}

1function PreviewItem(props: {
2  item: PreviewItemFragment$key;
3}) {
4  const item = useFragment(
5    graphql`
6      fragment PreviewItemFragment on Item @argumentDefinitions(
7        isForPreview: { type: "Boolean!" }
8      ) {
9        id @skip(if: $isForPreview)
10        title
11      }
12    `,
13    props.item
14  );
15
16  // ...
17}

1function PreviewItem(props: {
2  item: PreviewItemFragment$key;
3}) {
4  const item = useFragment(
5    graphql`
6      fragment PreviewItemFragment on Item @argumentDefinitions(
7        isForPreview: { type: "Boolean!" }
8      ) {
9        id @skip(if: $isForPreview)
10        title
11      }
12    `,
13    props.item
14  );
15
16  // ...
17}

1...PreviewItemFragment @arguments(isForPreview: true)

1...PreviewItemFragment @arguments(isForPreview: true)

Benefit #7: Better GraphQL APIs

Collocated fragments encourage you to build simple GraphQL APIs that are tailored to your UI components. It pushes you to move data complexity up to the backend, where it (often) belongs.

Benefits Summary

If you only absorb one thing, make it this: switching from hand-written GraphQL queries (whether you break them up into fragments or not) to GraphQL fragments collocated with your React components has many downstream benefits that instantly spoil you and make it impossible to go back.

Easy, pretty-good performance

This is your baseline. For no effort, all your GraphQL fragments are compiled and batched into queries. You should have 1 GraphQL network request per page/route, so that on page load you make 1 GraphQL query after your React components begin rendering.

This is already better than the average Apollo app and possibly good enough for:

• Enterprise/internal applications.
• Applications with a captive audience that won’t leave if performance isn’t the best it can be.
• Anything where shaving hundreds of milliseconds off page load time isn’t worth the developer cost of doing better.
• Applications with users on better computers & internet connections.
• Applications that have mostly desktop users.
• Etc.

Medium-effort, better performance

The next level of performance comes from decoupling data fetching from React rendering. The React team advocates render-as-you-fetch instead of fetch-on-render, which Relay-style GraphQL facilitates (with features like compiled, persisted queries and query preloading). When a person hits enter in the URL bar, your server should start fetching and streaming data in parallel to sending down the original HTML document. When a person clicks a button to open a modal with lazily-loaded contents, your server should start fetching the data for the modal (in parallel to the JS code powering the modal) as soon as the button is clicked. In this model you have 0 GraphQL network requests (from the client) per page/route, and 1 network request for every user interaction that initiates the need for more data.

This is good enough for just about every application, for example:

• Applications with users on high-latency mobile connections.
• Applications where more developer effort is worth the performance gains.
• Etc.

High-effort, best-possible performance

After batching larger and larger chunks of GraphQL into single queries, you’ll potentially run into issues where disproportionately slow field resolvers hold up the entire data fetch. Relay solves this by giving you the ability to control individual fields using the @defer and @stream directives.

Additionally, there are niche problems that aren’t caused by GraphQL but can be fixed by it. For example, let’s say you have a forum where people can make different kinds of posts and there is one React component to render each kind of post. Over time you’ve accumulated 1,000 kinds of posts which has caused your bundle size to balloon to something huge. You’ve observed that 98% of posts can be rendered with five components but the long tail of components all get used some small amount. What do you do? One solution: abandon client rendering and make your components non-interactive. An alternative: Relay’s Data-Driven Dependencies (3D) allows you to base what JS you send down to the client on what GraphQL data you’re about to return from the server. So you could include the five most-used components in your main bundle, always ready, and additionally send down just the React components needed to render the posts in the GraphQL response you’re about to send down.

While these aren’t common concerns, a Relay-style GraphQL framework should give you this level of control when needed.

This is good enough for every single application, including:

• Applications with billions of users where milliseconds saved is worth huge amounts of developer time.
• Applications with developers who can’t help but implement the fastest option even though it isn’t a good use of their time.

@required fields

GraphQL allows you to define non-nullable fields at the schema level, but it is well established that you should avoid doing so lest you cause resiliency and backwards-compatibility headaches for yourself. There is an incredibly high bar for using non-nullable fields in the schema.

That said, the bar inside your component is not nearly as high. It is reasonable when writing a component to say “if I don’t have this field, I might as well not render anything.” Relay has an @required directive that allows you to replace code like this:

1function IssueSummary(props: {
2  issue: IssueSummaryFragment$key;
3}) {
4  const issue = useFragment(
5    graphql`
6      fragment IssueSummaryFragment on Issue {
7        title
8        body
9        closed
10        createdAt
11      }
12    `,
13    props.issue
14  );
15
16  if (
17    issue.title == null ||
18    issue.body == null ||
19    issue.closed == null ||
20    issue.createdAt == null
21  ) {
22    return null;
23  }
24
25  return (
26    <li>
27      <h1>{issue.title}</h1>
28      <p>{issue.body}</p>
29      <p>{issue.closed}</p>
30      <p>{issue.createdAt}</p>
31    </li>
32  );
33}

1function IssueSummary(props: {
2  issue: IssueSummaryFragment$key;
3}) {
4  const issue = useFragment(
5    graphql`
6      fragment IssueSummaryFragment on Issue {
7        title
8        body
9        closed
10        createdAt
11      }
12    `,
13    props.issue
14  );
15
16  if (
17    issue.title == null ||
18    issue.body == null ||
19    issue.closed == null ||
20    issue.createdAt == null
21  ) {
22    return null;
23  }
24
25  return (
26    <li>
27      <h1>{issue.title}</h1>
28      <p>{issue.body}</p>
29      <p>{issue.closed}</p>
30      <p>{issue.createdAt}</p>
31    </li>
32  );
33}

with code like this:

1function IssueSummary(props: {
2  issue: IssueSummaryFragment$key;
3}) {
4  const issue = useFragment(
5    graphql`
6      fragment IssueSummaryFragment on Issue {
7        title @required(action: LOG)
8        body @required(action: LOG)
9        closed @required(action: LOG)
10        createdAt @required(action: LOG)
11      }
12    `,
13    props.issue
14  );
15
16  if (issue == null) {
17    return null;
18  }
19
20  return (
21    <li>
22      <h1>{issue.title}</h1>
23      <p>{issue.body}</p>
24      <p>{issue.closed}</p>
25      <p>{issue.createdAt}</p>
26    </li>
27  );
28}

1function IssueSummary(props: {
2  issue: IssueSummaryFragment$key;
3}) {
4  const issue = useFragment(
5    graphql`
6      fragment IssueSummaryFragment on Issue {
7        title @required(action: LOG)
8        body @required(action: LOG)
9        closed @required(action: LOG)
10        createdAt @required(action: LOG)
11      }
12    `,
13    props.issue
14  );
15
16  if (issue == null) {
17    return null;
18  }
19
20  return (
21    <li>
22      <h1>{issue.title}</h1>
23      <p>{issue.body}</p>
24      <p>{issue.closed}</p>
25      <p>{issue.createdAt}</p>
26    </li>
27  );
28}

That might not be a huge number of characters saved but:

• You’re no longer keeping two lists of fields in sync.
• Your TypeScript types are immediately what you want: either the entire issue is null, or you have all the fields you require as non-nullable.
• The Relay version logs to your telemetry endpoint when a field is unexpectedly null instead of the code on the left which just silently ignores it.
• @required supports other behavior, such as throwing an exception if a field is null, for when that makes sense. These exceptions are thrown at a single choke point with structured data about the fragment/field that eroded, making them easy to setup global monitoring for regressions. That makes these errors highly actionable in a way that you might not get with ad-hoc error logging.
• You can use @required to bubble a null field up through the component hierarchy in a way that doesn’t work with just returning null.
• Etc.

Language Server Protocol / VS Code Extension

By moving GraphQL into your components you’re also moving the benefits of your language-server protocol closer to your components. See above for how you get schema documentation right in your components.