Relay- Facebook’s GraphQL Client for React

A spectacular combination of React, GraphQL, and Relay!!

ByPayal Mittal
May 7th . 5 min read
Relay- Facebook’s GraphQL Client for React

When React was first released by Facebook to create responsive user interfaces, there was much that was left undone in this approach.

The developers were not sure how to design a website with React. Although, the Flux architecture of Facebook served some help but not much. But, with the release of Relay, React became a fully-fledged framework and able to provide reliable solutions.

In this blog, we’ll understand Relay in theoretical terms, such as its features, characteristics, additions in its new version, and much more. Let’s get to know a more pronounced definition of Relay-

What is Relay?

Relay is Facebook’s homegrown GraphQL client that they open-sourced alongside GraphQL in the year 2015. It is an open-source JavaScript framework used to build data-driven React applications backed by GraphQL.

Much to your delight, the applications built are easy to use, extensible, and most importantly, highly effective & performant. The Relay library couples React and GraphQL together and progress the concept of encapsulation further.

“Relay was designed to be performant from the ground up, and to support scaling your application to thousands of components, while keeping the management of data fetching sane, and fast iteration speeds as your application grows and changes.”

It was built as a routing framework at first but, eventually, it got combined with data-loading responsibilities and now it works with various routing options.

Relay is a relief to work with, providing ahead-of-time safety while working on a project. The Relay compiler ensures consistency throughout your project against the GraphQL schema.

Why a GraphQL Client?

Like Relay, there are other GraphQL client libraries available out there such as Apollo. But the big question is- why do we need a GraphQL client?

Well, the GraphQL clients are used to accomplish tasks that are repetitive to the app. These client libraries provide you some command over ongoing operations.

For instance, sending queries and mutations without having to maintain a local cache and attend lower-level networking particulars. This is the functionality sought in every frontend application and why build it on your own when you have the advantage of a GraphQL client?

Relay’s Features -

According to the Facebook team, Relay is defined by its three primary characteristics-

1) Declarative: You no longer need to use imperative APIs to interact with your data store. All you have to do is to declare the data needed by your components using GraphQL and Relay will determine when and how to fetch your data.

2) Colocation: The GraphQL queries are placed right next to the views that rely on them. Furthermore, Relay aggregates these queries into efficient network-requests to fetch only the queries you needed.

3) Mutations: Relay lets you write mutations and provides data consistency, automatic updates, reverting changes, and error handling. Also, it is capable of merging mutation updates.

Relay possesses several other extensive features that make it a preferable choice for developers, such as-

  • Fast iteration speed
  • Minimal round trips to fetch data
  • Automatic data consistency
  • Support executing GraphQL mutations
  • Merging mutation updates
  • Ahead-of-time Optimization
  • Extensible and reusable
  • Make complexity explicit


First and foremost, as we know that Relay framework is used for data management in React applications, so it is necessary to have a good knowledge of React.

You would also require a basic understanding of GraphQL. Unlike React, where you can start working on any project at once, Relay applications have three forthright requirements that you must justify before start working-

  • A GraphQL Schema

  • A GraphQL Server

  • Relay

Also can read - Relay Hooks(facebook's newly improved react-hooks)

‘Relay Modern’ and Its Architecture:

Well, it is quite obvious that ‘Relay Modern’ is the modern or newest version of Relay. It has many advantages over its previous version, for instance — high extensibility, easy-to-use functionality, ahead-of-time code generation, and above all, improved performance on mobile devices.

Relay Modern comprises of three core modules, as under-

  • Relay Compiler: It provides services to transform and optimize queries and generate build artifacts. One of the novel features of the compiler is to facilitate experiments with new GraphQL features as custom directives by making the code translation easier.
  • Relay Runtime: This full-featured GraphQL runtime is used to build high-level client APIs. It features optimized ‘read’ and ‘write’ operations, abstraction for pagination, garbage collection to remove unreferenced cache data, arbitrary logic, optimistic mutations, normalized object cache, support for GraphQL live queries, and subscriptions, and much more.
  • React/Relay: Featuring a high-level product API to integrate React to Relay runtime and to fetch data for queries or defining data dependencies for containers.

What’s New with Relay Modern -

Let’s see what is new in Relay Modern that differs it from Relay-

Compatibility Mode:

The new feature in the form of ‘Compatibility Mode’ allows existing Relay applications to easily adopt this new version API. Also, it renders the following functions-

  • Simpler mutation API
  • Static mutation query
  • Arbitrary nesting of fields
  • Removal of query restrictions while using QueryRenderer
  • Selective use of Route
  • Direct rendering of data without having the need for a container to access the data. However, with the increase in the size and complexity of your application, one can use Containers.

Modern Runtime:

While the Relay application got converted to Compat API (Compatible), the Relay Modern runtime features more functions, in addition to those mentioned above. Let’s have a quick look at these functions-

>>Effectiveness: The Relay Modern core is way too light and faster in comparison to its previous version. Now that we can use static queries in Relay Modern, it’s now easier to move more work to build and compile. Also, having no longer need to track information for dynamic queries, there’s been a huge reduction in memory overhead of using Relay.

>>Garbage Recycling: Reduction in memory usage due to the automatic removal of cached data, which is no more needed during execution.

>>Simple Mutation API: With the introduction of the new mutation API in Relay Modern, you can update fields and data transparently.

GraphQL in Relay:

Relay provides a graphqltag that is used to write queries, mutations, fragments, or subscriptions in GraphQL language. For instance-

import {graphql} from 'react-relay';
  query MyQuery {
    viewer {

The graphqltemplate tags are the runtime representation (but they never executed at runtime!) of the GraphQL document to define query renderers, fragment, re-fetch, and pagination containers.

Summary -

While, GraphQL is a query language and provides robust tools to build powerful and high-performance client applications, React, on the other hand, is a JavaScript framework for building responsive and outstanding user-interfaces.

Relay uses GraphQL to fetch data for React, taking care of exactly what data is required, and helps building applications having optimized performance and provides out-of-box solutions.

A spectacular combination is- React, GraphQL, and Relay, don’t you think??

I’m grateful that you have read this blog till the very end. Thanks!! If you liked it, let me know by adding your claps to it. Also, read full blog Preact — A Clever Alternative of react