Building a React application is not only about creating a user interface. It also has tricky parts like data fetching, re-render performance, and scalability. Many libraries and frameworks try to solve these problems, like Redux, Sagas, etc. But these tools come with their own set of difficulties.

Redux gives you a single data source, but all the data fetching and rendering logic is handled by developers. Immer gives you immutable data structures, but one needs to handle the re-render performance of applications.

GraphQL helps developers design and expose APIs on the backend, but no tool on the client side could utilize the full advantage of the single endpoint and data schema provided by GraphQL.

In this article, we will learn about Relay as a GraphQL client. What are the advantages of using Relay in your application, and what conventions are required to integrate it?  We’ll also cover how following those conventions will give you a better developer experience and a performant app. We will also see how applications built with Relay are modular, scalable, efficient, and, by default, resilient to change.

About Relay

Relay is a JavaScript framework to declaratively fetch and manage your GraphQL data inside a React application. Relay uses static queries and ahead-of-time compilation to help you build a high-performance app. 

But as the great saying goes, “With great power comes great responsibilities.” Relay comes with a set of costs (conventions), which—when compared with the benefits you get—is well worth it. We will explore the trade-offs in this article.

The Relay framework is built of multiple modules:

1. The compiler: This is a set of modules designed to extract GraphQL code from across the codebase and do validations and optimizations during build time.

2. Relay runtime: A high-performance GraphQL runtime that features a normalized cache for objects and highly optimized read/write operations, simplified abstractions over fetching data fields, garbage collection, subscriptions, and more.

3. React-relay: This provides the high-level APIs to integrate React with the Relay runtime.

The Relay compiler runs as a separate process, like how webpack works for React. It keeps watching and compiling the GraphQL code, and in case of errors, it simply does not build your code, which prevents bugs from going into higher environments.

Fragments

Fragments are at the heart of how Relay blends with GraphQL. A fragment is a selection of fields on a GraphQL type. 

fragment Avatar_user on User {
  avatarImgUrl
  firstName
  lastName
  userName
}

fragment Avatar_user on User {
  avatarImgUrl
  firstName
  lastName
  userName
}

If we look at the sample fragment definition above, the fragment name, Avatar_user, is not just a random name. One of the Relay framework’s important conventions is that fragments have globally unique fragment names and follow a structure of <modulename>_<propertyname>. The example above is a fragment definition for Avatar_user.</propertyname></modulename>

This fragment can then be reused throughout the queries instead of selecting the fields manually to render the avatar in each view.

In the below query, we see the author type, and the first two who liked the blog post can use the fragment definition of Avatar_user

query GetBlogPost($postId: ID!) {
      blogPostById(id: $postId) {
        author {
          firstName
          lastName
          avatarImgUrl
          userName
        }
        likedBy(first: 2) {
          edges {
            node {
              firstName
              lastName
              avatarImgUrl
              userName
            }
          }
        }
      }
    }

query GetBlogPost($postId: ID!) {
      blogPostById(id: $postId) {
        author {
          firstName
          lastName
          avatarImgUrl
          userName
        }
        likedBy(first: 2) {
          edges {
            node {
              firstName
              lastName
              avatarImgUrl
              userName
            }
          }
        }
      }
    }

Now, our new query with fragments looks like this:

query GetBlogPost($postId: ID!) {
      blogPostById(id: $postId) {
        author {
          ...Avatar_user
        }
        likedBy(first: 2) {
          edges {
            node {
              ...Avatar_user
            }
          }
        }
      }
    }

query GetBlogPost($postId: ID!) {
      blogPostById(id: $postId) {
        author {
          ...Avatar_user
        }
        likedBy(first: 2) {
          edges {
            node {
              ...Avatar_user
            }
          }
        }
      }
    }

Fragments not only allow us to reuse the definitions but more essentially, they let us add or remove fields needed to render our avatar as we evolve our application.

Another highly important client-side convention is colocation. This means the data required for a component lives inside the component. This makes maintenance and extending much easier. Just like how React allows us to break our UI elements into components and group/compose different views, fragments in Relay allow us to split the data definitions and colocate the data and the view definitions.

So, a good practice is to define single or multiple fragments that contain the data component to be rendered. This means that a component depends on some fields from the user type, irrespective of the parent component. In the example above, the <avatar> component will render an avatar using the fields specified in the Avatar_user fragment named.</avatar>

How Relay leverages the GraphQL Fragment

Relay wants all components to enlist all the data it needs to render, along with the component itself. Relay uses data and fragments to integrate the component and its data requirement. This convention mandates that every component lists the fields it needs access to. 

Other advantages of the above are:

1. Components are not dependent on data they don’t explicitly request.
2. Components are modular and self-contained.
3. Reusing and refactoring the components becomes easier.

Performance

In Relay, the component re-renders only when its exact fields change, and this feature available is out of the box. The fragment subscribes to updates specifically for data the component selects. This lets Relay enhance how the view is updated, and performance is not affected as codebase scales.

Now, let’s look at an example of components in a single post of a blog application. Here is a wireframe of a sample post to give an idea of the data and view required.

Now, let’s write a plain query without Relay, which will fetch all the data in a single query. It will look like this for the above wireframe:

query GetBlogPost($postId: ID!) {
      blogPostById(id: $postId) {
        author {
          firstName
          lastName
          avatarUrl
          shortBio
        }
        title
        coverImgUrl
        createdAt
        tags {
          slug
          shortName
        }
        body
        likedByMe
        likedBy(first: 2) {
          totalCount
          edges {
            node {
              firstName
              lastName
              avatarUrl
            }
          }
        }
      }
    }

query GetBlogPost($postId: ID!) {
      blogPostById(id: $postId) {
        author {
          firstName
          lastName
          avatarUrl
          shortBio
        }
        title
        coverImgUrl
        createdAt
        tags {
          slug
          shortName
        }
        body
        likedByMe
        likedBy(first: 2) {
          totalCount
          edges {
            node {
              firstName
              lastName
              avatarUrl
            }
          }
        }
      }
    }

This one query has all the necessary data. Let’s also write down a sample structure of UI components for the query above:

<BlogPostContainer>
    <BlogPostHead>
      <BlogPostAuthor>
        <Avatar />
      </BlogPostAuthor>
    </BlogPostHead>
    <BlogPostBody>
      <BlogPostTitle />
      <BlogPostMeta>
        <CreatedAtDisplayer />
        <TagsDisplayer />
      </BlogPostMeta>
      <BlogPostContent />
      <LikeButton>
        <LikedByDisplayer />
      </LikeButton>
    </BlogPostBody>
 </BlogPostContainer>

<BlogPostContainer>
    <BlogPostHead>
      <BlogPostAuthor>
        <Avatar />
      </BlogPostAuthor>
    </BlogPostHead>
    <BlogPostBody>
      <BlogPostTitle />
      <BlogPostMeta>
        <CreatedAtDisplayer />
        <TagsDisplayer />
      </BlogPostMeta>
      <BlogPostContent />
      <LikeButton>
        <LikedByDisplayer />
      </LikeButton>
    </BlogPostBody>
 </BlogPostContainer>

In the implementation above, we have a single query that will be managed by the top-level component. It will be the top-level component’s responsibility to fetch the data and pass it down as props. Now, we will look at how we would build this in Relay:

import * as React from "react";
    import { GetBlogPost } from "./__generated__/GetBlogPost.graphql";
    import { useLazyLoadQuery } from "react-relay/hooks";
    import { BlogPostHead } from "./BlogPostHead";
    import { BlogPostBody } from "./BlogPostBody";
    import { graphql } from "react-relay";
    interface BlogPostProps {
      postId: string;
    }
    export const BlogPost = ({ postId }: BlogPostProps) => {
      const { blogPostById } = useLazyLoadQuery<GetBlogPost>(
        graphql`
          query GetBlogPost($postId: ID!) {
            blogPostById(id: $postId) {
              ...BlogPostHead_blogPost
              ...BlogPostBody_blogPost
            }
          }
        `,
        {
          variables: { postId }
        }
      );
      if (!blogPostById) {
        return null;
      }
      return (
        <div>
          <BlogPostHead blogPost={blogPostById} />
          <BlogPostBody blogPost={blogPostById} />
        </div>
      );
    };

import * as React from "react";
    import { GetBlogPost } from "./__generated__/GetBlogPost.graphql";
    import { useLazyLoadQuery } from "react-relay/hooks";
    import { BlogPostHead } from "./BlogPostHead";
    import { BlogPostBody } from "./BlogPostBody";
    import { graphql } from "react-relay";


    interface BlogPostProps {
      postId: string;
    }

    export const BlogPost = ({ postId }: BlogPostProps) => {
      const { blogPostById } = useLazyLoadQuery<GetBlogPost>(
        graphql`
          query GetBlogPost($postId: ID!) {
            blogPostById(id: $postId) {
              ...BlogPostHead_blogPost
              ...BlogPostBody_blogPost
            }
          }
        `,
        {
          variables: { postId }
        }
      );

      if (!blogPostById) {
        return null;
      }

      return (
        <div>
          <BlogPostHead blogPost={blogPostById} />
          <BlogPostBody blogPost={blogPostById} />
        </div>
      );
    };

First, let’s look at the query used inside the component:

const { blogPostById } = useLazyLoadQuery<GetBlogPost>(
graphql`
  query GetBlogPost($postId: ID!) {
    blogPostById(id: $postId) {
      ...BlogPostHead_blogPost
      ...BlogPostBody_blogPost
    }
  }
`,
{
  variables: { postId }
}
);

const { blogPostById } = useLazyLoadQuery<GetBlogPost>(
graphql`
  query GetBlogPost($postId: ID!) {
    blogPostById(id: $postId) {
      ...BlogPostHead_blogPost
      ...BlogPostBody_blogPost
    }
  }
`,
{
  variables: { postId }
}
);

The useLazyLoadQuery React hook from Relay will start fetching the GetBlogPost query just as the component renders. 

NOTE: The useLazyLoadQuery is used here as it follows a common mental model of fetching data after the page is loaded. However, Relay encourages data to be fetched as early as possible using the usePreladedQuery hook. 

For type safety, we are annotating the useLazyLoadQuery with the type GetBlogPost, which is imported from ./__generated__/GetBlogPost.graphql. This file is auto-generated and synced by the Relay compiler. It contains all the information about the types needed to be queried, along with the return type of data and the input variables for the query.

The Relay compiler takes all the declared fragments in the codebase and generates the type files, which can then be used to annotate a particular component.

The GetBlogPost query is defined by composing multiple fragments. Another great aspect of Relay is that there is no need to import the fragments manually. They are automatically included by the Relay compiler. Building the query by composing fragments, just like how we compose our component, is the key here. 

Another approach can be to define queries per component, which takes full responsibility for its data requirements. But this approach has two problems: 

1. Multiple queries are sent to the server instead of one.

2. The loading will be slower as components would have to wait till they render to start fetching the data.

In the above example, the GetBlogPost only deals with including the fragments for its child components, BlogPostHead and BlogPostBody. It is kept hidden from the actual data fields of the children component.

When using Relay, components define their data requirement by themselves. These components can then be composed along with other components that have their own separate data. 

At the same time, no component knows what data the other component needs except from the GraphQL type that has the required component data. Relay makes sure the right data is passed to the respective component, and all input for a query is sent to the server.

This allows developers to think only about the component and fragments as one while Relay does all the heavy lifting in the background. Relay minimizes the round-trips to the server by placing the fragments from multiple components into optimized and efficient batches. 

As we said earlier, the two fragments, BlogPostHead_blogPost and BlogPostBody_blogPost, which we referenced in the query, are not imported manually. This is because Relay imposes unique fragment names globally so that the compiler can include the definitions in queries sent to the server. This eliminates the chances of errors and takes away the laborious task of referencing the fragments by hand. 

 if (!blogPostById) {
      return null;
  }
  return (
    <div>
      <BlogPostHead blogPost={blogPostById} />
      <BlogPostBody blogPost={blogPostById} />
    </div>
  );

 if (!blogPostById) {
      return null;
  }

  return (
    <div>
      <BlogPostHead blogPost={blogPostById} />
      <BlogPostBody blogPost={blogPostById} />
    </div>
  );

Now, in the rendering logic above, we render the <BlogPostHead/> and <BlogPostBody/> and pass the blogPostById object as prop. It’s passed because it is the object inside the query that spreads the fragment needed by the two components. This is how Relay transfers fragment data. Because we spread both fragments on this object, it is guaranteed to satisfy both components.

To put it into simpler terms, we say that to pass the fragment data, we pass the object where the fragment is spread, and the component then uses this object to get the real fragment data. Relay, through its robust type systems, makes sure that the right object is passed with required fragment spread on it.

The previous component, the BlogPost, was the Parent component, i.e., the component with the root query object. The root query is necessary because it cannot fetch a fragment in isolation. Fragments must be included in the root query in a parent component. The parent can, in turn, be a fragment as long the root query exists in the hierarchy. Now, we will build the BlogPostHead component using fragments:

 import * as React from "react";
    import { useFragment } from "react-relay/hooks";
    import { graphql } from "react-relay";
    import {
      BlogPostHead_blogPost$key, BlogPostHead_blogPost
    } from "./__generated__/BlogPostHead_blogPost.graphql";
    import { BlogPostAuthor } from "./BlogPostAuthor";
    import { BlogPostLikeControls } from "./BlogPostLikeControls";
    interface BlogPostHeadProps {
      blogPost: BlogPostHead_blogPost$key;
    }
    export const BlogPostHead = ({ blogPost }: BlogPostHeadProps) => {
      const blogPostData = useFragment<BlogPostHead_blogPost>(
        graphql`
          fragment BlogPostHead_blogPost on BlogPost {
            title
            coverImgUrl
            ...BlogPostAuthor_blogPost
            ...BlogPostLikeControls_blogPost
          }
        `,
        blogPost
      );
      return (
        <div>
          <img src={blogPostData.coverImgUrl} />
          <h1>{blogPostData.title}</h1>
          <BlogPostAuthor blogPost={blogPostData} />
          <BlogPostLikeControls blogPost={blogPostData} />
        </div>
      );
    };

 import * as React from "react";
    import { useFragment } from "react-relay/hooks";
    import { graphql } from "react-relay";
    import {
      BlogPostHead_blogPost$key, BlogPostHead_blogPost
    } from "./__generated__/BlogPostHead_blogPost.graphql";
    import { BlogPostAuthor } from "./BlogPostAuthor";
    import { BlogPostLikeControls } from "./BlogPostLikeControls";

    interface BlogPostHeadProps {
      blogPost: BlogPostHead_blogPost$key;
    }

    export const BlogPostHead = ({ blogPost }: BlogPostHeadProps) => {
      const blogPostData = useFragment<BlogPostHead_blogPost>(
        graphql`
          fragment BlogPostHead_blogPost on BlogPost {
            title
            coverImgUrl
            ...BlogPostAuthor_blogPost
            ...BlogPostLikeControls_blogPost
          }
        `,
        blogPost
      );

      return (
        <div>
          <img src={blogPostData.coverImgUrl} />
          <h1>{blogPostData.title}</h1>
          <BlogPostAuthor blogPost={blogPostData} />
          <BlogPostLikeControls blogPost={blogPostData} />
        </div>
      );
    };

NOTE: In our example, the BlogPostHead and BlogPostBody define only one fragment, but in general, a component can have any number of fragments or GraphQL types and even more than one fragments on the same type.

In the component above, two type definitions, namely BlogPostHead_blogPost$key and BlogPostHead_blogPost, are imported from the file BlogPostHead_blogPost.graphql, generated by the Relay compiler. The compiler extracts the fragment code from this file and generates the types. This process is followed for all the GraphQL code—queries, mutations, fragments, and subscriptions.

The blogPostHead_blogPost has the fragment type definitions, which is then passed to the useFragment hook to ensure type safety when using the data from the fragment. The other import, blogPostHead_blogPost$key, is used in the interface Props { … }, and this type definition makes sure that we pass the right object to useFragment. Otherwise,  the type system will throw errors during build time. In the above child component, the blogPost object is received as a prop and is passed to useFragment as a second parameter. If the blogPost object did not have the correct fragment, i.e., BlogPostHead_blogPost, spread on it, we would have received a type error. Even if there were another fragment with exact same data selection spread on it, Relay makes sure it’s the right fragment that we use with the useFragement. This allows you to change the update fragment definitions without affecting other components.

Data masking

In our example, the fragment BlogPostHead_blogPost explicitly selects two fields for the component:

1. title
2. coverImgUrl

This is because we use/access only these two fields in the view for the <blogposthead></blogposthead> component. So, even if we define another fragment, BlogPostAuthor_blogPost, which selects the title and coverImgUrl, we don’t receive access to them unless we ask for them in the same fragment. This is enforced by Relay’s type system both at compile time and at runtime. This safety feature of Relay makes it impossible for components to depend on data they do not explicitly select. So, developers can refactor the components without risking other components. To reiterate, all components and their data dependencies are self-contained.

The data for this component, i.e., title and coverImgUrl, will not be accessible on the parent component, BlogPost, even though the props object is sent by the parent. The data becomes available only through the useFragment React hook. This hook can consume the fragment definition. The useFragment takes in the fragment definition and the object where the fragment is spread to get the data listed for the particular fragment.  

Just like how we spread the fragment for the BlogPostHead component in the BlogPost root query, we an also extend this to the child components of BlogPostHead. We spread the fragments, i.e., BlogPostAuthor_blogPost, BlogPostLikeControls_blogPost, since we are rendering <BlogPostAuthor /> and <BlogPostLikeControls />.

NOTE: The useFragment hook does not fetch the data. It can be thought of as a selector that grabs only what is needed from the data definitions.

Performance

When using a fragment for a component, the component subscribes only to the data it depends on. In our example, the component BlogPostHead will only automatically re-render when the fields “coverImgUrl” or “title” change for a specific blog post the component renders. Since the BlogPostAuthor_blogPost fragment does not select those fields, it will not re-render. Subscription to any updates is made on fragment level. This is an essential feature that works out of the box with Relay for performance.

Let us now see how general data and components are updated in a different GraphQL framework than Relay. The data that gets rendered on view actually comes from an operation that requests data from the server, i.e., a query or mutation. We write the query that fetches data from the server, and that data is passed down to different components as per their needs as props. The data flows from the root component, i.e., the component with the query, down to the components. 

Let’s look at a graphical representation of the data flow in other GraphQL frameworks:

Image source: Dev.to

NOTE: Here, the framework data store is usually referred to as cache in most frameworks:

1. The Profile component executes the operation ProfileQuery to a GraphQL server.

2. The data return is kept in some framework-specific representation of the data store.

3. The data is passed to the view rendering it.

4. The view then passes on the data to all the child components who need it. Example: Name, Avatar, and Bio. And finally React renders the view.

In contrast, the Relay framework takes a different approach:

Image source: Dev.to

Let’s breakdown the approach taken by Relay: 

• For the initial part, we see nothing changes. We still have a query that is sent to the GraphQL server and the data is fetched and stored in the Relay data store.
• What Relay does after this is different. The components get the data directly from the cache-store(data store). This is because the fragments help Relay integrate deeply with the component data requirements.The component fragments get the data straight from the framework data store and do not rely on data to be passed down as props. Although some information is passed from the query to the fragments used to look up the particular data needed from the data store, the data is fetched by the fragment itself.

To conclude the above comparison, in other frameworks (like Apollo), the component uses the query as the data source. The implementation details of how the root component executing the query sends data to its descendants is left to us. But Relay takes a different approach of letting the component take care of the data in needs from the data store.

In an approach used by other GraphQL frameworks, the query is the data source, and updates in the data store forces the component holding the query to re-render. This re-render cascades down to any number of components even if those components do not have to do anything with the updated data other than acting as a layer to pass data from parent to child. In the Relay approach, the components directly subscribe to the updates for the data used. This ensures the best performance as our app scales in size and complexity.

Developer Experience

Relay removes the responsibility of developers to route the data down from query to the components that need it. This eliminates the changes of developer error. There is no way for a component to accidentally or deliberately depend on data that it should be just passing down in the component tree if it cannot access it. All the hard work is taken care of by the Relay framework if we follow the conventions discussed.

Conclusion

To summarize, we detailed all the work Relay does for us and the effects:

• The type system of the Relay framework makes sure the right components get the right data they need. Everything in Relay revolves around fragments.
• In Relay, fragments are coupled and colocated with components, which allows it to mask the data requirements from the outside world. This increases the readability and modularity.
• By default, Relay takes care of performance as components only re-render when the exact data they use change in the data store.
• Type generation is a main feature of Relay compiler. Through type generation, interactions with the fragment’s data is typesafe.

Conventions enforced by Relay’s philosophy and architecture allows it to take advantage of the information available about your component. It knows the exact data dependencies and types. It uses all this information to do a lot of work that developers are required to deal with.

Related Articles

1. Enable Real-time Functionality in Your App with GraphQL and Pusher

2. Build and Deploy a Real-Time React App Using AWS Amplify and GraphQL