Step-by-step Guide
Relay is a framework for managing and declaratively fetching GraphQL data. It allows developers to declare what data each component needs via GraphQL, and then aggregate these dependencies and efficiently fetch the data in fewer round trips. In this guide we'll introduce the key concepts for using Relay in a React app one at a time.
#
Step 1: Create React AppFor this example we'll start with a standard install of Create React App. Create React App makes it easy to get a fully configured React app up and running and also supports configuring Relay. To get started, create a new app with:
At this point we should be able to change to the app's directory and run it:
For troubleshooting and more setup options, see the Create React App documentation.
#
Step 2: Fetch GraphQL (without Relay)If you're exploring using GraphQL with Relay, we highly recommend starting with a basic approach and using as few libraries as possible. GraphQL servers can generally be accessed using plain-old HTTP requests, so we can use the fetch
API to request some data from our server. For this guide we'll use GitHub's GraphQL API as the server, but if you already have a GraphQL server feel free to use that instead.
#
2.1: GitHub GraphQL AuthenticationTo start we'll need an authentication token for the GitHub API (if you're using your own GraphQL endpoint, you can skip this step):
- Open github.com/settings/tokens.
- Ensure that at least the
repo
scope is selected. - Generate a token
- Create a file
./your-app-name/.env.local
and add the following contents, replacing<TOKEN>
with your authentication token:
#
2.2: A fetchGraphQL HelperNext let's update the home screen of our app to show the name of the Relay repository. We'll start with a common approach to fetching data in React, calling our fetch function after the component mounts (note: later we'll see some limitations of this approach and a better alternative that works with React Concurrent Mode and Suspense). First we'll create a helper function to load data from the server. Again, this example will use the GitHub API, but feel free to replace it with the appropriate URL and authentication mechanism for your own GraphQL server:
#
2.3: Fetching GraphQL From ReactNow we can use our fetchGraphQL
function to fetch some data in our app. Open src/App.js
and edit it as follows:
#
Step 3: When To Use RelayAt this point we can fetch data with GraphQL and render it with React. This is a reasonable solution that can be sufficient for many apps. However, this approach doesn't necessarily scale. As our app grows in size and complexity, or the number of people working on the app grows, a simple approach like this can become limiting. Relay provides a number of features designed to help keep applications fast and reliable even as they grow in size and complexity: colocating data dependencies in components with GraphQL fragments, data consistency, mutations, etc. Check out Thinking in GraphQL and Thinking in Relay for an overview of how Relay makes it easier to work with GraphQL.
#
Step 4: Adding Relay To Our ProjectIn this guide we'll demonstrate installing the experimental release of Relay Hooks, a new, hooks-based Relay API that supports React Concurrent Mode and Suspense.
First we'll add the necessary packages. Note that Relay is comprised of three key pieces: a compiler (which is used at build time), a core runtime (that is React agnostic), and a React integration layer.
#
4.1 Configure Relay CompilerNext let's configure Relay compiler. We'll need a copy of the schema as a .graphql
file. If you're using the GitHub GraphQL API, you can download a copy directly from the Relay example app:
Note: On Windows, the .graphql
file has to be explicitly saved with UTF-8 encoding, not the default UTF-16. See this issue for more details.
If you're using your own API we suggest using the get-graphql-schema
utility to download your schema into a .graphql
file.
Now that we have a schema we can modify package.json
to run the compiler first whenever we build or start our app:
At this point, you should be able to run the following successfully:
If it works, your app will open at localhost:3000. Now when we write GraphQL in our app, Relay will detect it and generate code to represent our queries in your-app-name/src/__generated__/
. We recommend checking in these generated files to source control.
#
4.2 Configure Relay RuntimeNow that the compiler is configured we can set up the runtime - we have to tell Relay how to connect to our GraphQL server. We'll reuse the fetchGraphQL
utility we built above. Assuming you haven't modified it (or at least that it still takes text
and variables
as arguments), we can now define a Relay Environment
. An Environment
encapsulates how to talk to our server (a Relay Network
) with a cache of data retrieved from that server. We'll create a new file, src/RelayEnvironment.js
and add the following:
#
Step 5: Fetching a Query With RelayNow that Relay is installed and configured we can change App.js
to use it instead. We'll prepare our data as the app starts, and wait for it to be ready in <App>
. Replace the contents of src/App.js
with the following:
Note that you'll have to restart the app - yarn start
- so that Relay compiler can see the new query and generate code for it. See the Relay Compiler setup docs for how to run Relay Compiler in watch mode, to regenerate code as you modify queries.
#
Step 6: Explore!At this point we have an app configured to use Relay. We recommend checking out the following for information and ideas about where to go next:
- The Guided Tour describes how to implement many common use-cases.
- The API Reference has full details on the Relay Hooks APIs.
- The Example App is a more sophisticated version of what we've started building here. It includes routing integration and uses React Concurrent Mode and Suspense for smooth transitions between pages.
Is this page useful?