How to use Relay: install, run the example and learn the basics

What Relay does and who it is for

Relay lets React components declare their data requirements with GraphQL instead of calling a data store through an imperative API. Relay then works out how and when to fetch that data.

Relay is built for React developers who already use GraphQL, and for teams with large React apps that need consistent data across many components. It is not a good fit for projects that do not use React, for teams without a GraphQL API, or for beginners who are new to both React and GraphQL.

• Declarative: you describe the data you need and Relay handles fetching.
• Colocation: queries live next to the views that use them, and Relay combines them into efficient network requests.
• Mutations: you change data with GraphQL mutations, with automatic data consistency, optimistic updates and error handling.

Install Relay by running the TodoMVC example

The simplest way to try Relay is the TodoMVC example in the relay-examples repository. Relay is installed by cloning and building this example, and Yarn is the package manager used in the instructions. The README does not state a Yarn version.

Clone the repository, move into the todo folder, then install dependencies and start the dev server.

• Prerequisite: Yarn.
• The example runs on a local dev server.
• After starting it, open http://localhost:5173 in your browser.

Understand the commands in the example

The README lists four Yarn steps after cloning. yarn installs the dependencies. yarn dev starts the dev server. The README also runs yarn grats and yarn relay before the dev server starts, so follow the full sequence shown in the example.

The README does not explain what each of these scripts does internally, so check the example's own files if you need more detail.

• yarn: install dependencies.
• yarn grats: run before starting the app, as shown in the README.
• yarn relay: run before starting the app, as shown in the README.
• yarn dev: start the development server.

Learn the core ideas: declare data, colocate queries, mutate

In Relay, each component states the GraphQL data it depends on. Because the query sits beside the view, you can read a component and see exactly what it uses.

To change data, Relay uses GraphQL mutations on the client and server. Relay also supports optimistic updates, which the README lists as part of its mutation support.

• Write a GraphQL query next to the component that renders its data.
• Let Relay combine queries into network requests for only the data needed.
• Use GraphQL mutations to change data, with optimistic updates and error handling.

Check Relay against other data libraries

Relay is one of several options for fetching data in React. The comparable projects listed for this page are Apollo Client, urql, React Query and relay-hooks.

Relay is the stronger choice when you want the framework to handle fetching and your team already uses GraphQL. If you do not use GraphQL or want a lighter setup, one of the other listed projects may suit you better.