Quick Start

This quick start guide will start with a new React app using Vite and show you how to add Relay to it.

tip

If you'd prefer an automated approach, create-relay-app by Tobias Tengler will walk you through adding Relay to an existing React app via a series of prompts: npm create @tobiastengler/relay-app

We will be building a simple app which shows Star Wars movies fetched from the example Star Wars GraphQL API hosted by graphql.org.

Scaffold a React App

We’ll start with a Vite React app using TypeScript.

npm create vite -- --template react-ts

You’ll be prompted for a project name. Type: relay-example

Install Dependencies

cd relay-example

# Note: Version 18^ of Relay is missing React 19 as a peer dependency. This will be fixed in the next release. Until then we must add `--force` to the following commands.

# Runtime dependencies
npm install relay-runtime react-relay --force
# Dev dependencies
npm install --dev vite-plugin-relay relay-compiler --force
# Types
npm install --dev @types/relay-runtime @types/react-relay --force

Configure Vite to use Relay

Relay uses a Babel plugin to insert code generated by the Relay compiler into your bundle. We can enable that transform in Vite with the vite-plugin-relay plugin:

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import relay from 'vite-plugin-relay';

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    relay
  ],
})

See Babel Plugin for information about how to configure the Babel plugin for other build systems.

Configure the Relay Compiler

Next we will download the schema for the Star Wars GraphQL endpoint and configure the Relay compiler to use that schema:

curl -O https://raw.githubusercontent.com/graphql/swapi-graphql/refs/heads/master/schema.graphql

relay.config.json

{
  "src": "./src",
  "schema": "./schema.graphql",
  "language": "typescript",
  "eagerEsModules": true
}

See Relay Compiler for more information about configuring and running the Relay compiler.

Configure your Relay Environment

To allow components within our application to fetch GraphQL we configure a Relay Environment to fetch from our test endpoint and add it to React context.

src/main.tsx

import { StrictMode, Suspense } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";
import { RelayEnvironmentProvider } from "react-relay";
import {
  Environment,
  Store,
  RecordSource,
  Network,
  FetchFunction,
} from "relay-runtime";

const HTTP_ENDPOINT = "https://graphql.org/graphql/";

const fetchGraphQL: FetchFunction = async (request, variables) => {
  const resp = await fetch(HTTP_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: request.text, variables }),
  });
  if (!resp.ok) {
    throw new Error("Response failed.");
  }
  return await resp.json();
};

const environment = new Environment({
  store: new Store(new RecordSource({})),
  network: Network.create(fetchGraphQL),
});

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <RelayEnvironmentProvider environment={environment}>
      <Suspense fallback="Loading...">
        <App />
      </Suspense>
    </RelayEnvironmentProvider>
  </StrictMode>
);

See Relay Environment for an overview of the Relay Environment and how to configure it.

Define your first Relay component

Finally we can start defining the data we want to fetch and build our UI:

src/App.tsx

import { AppQuery } from "./__generated__/AppQuery.graphql";
import { graphql, useLazyLoadQuery } from "react-relay";

export default function App() {
  const data = useLazyLoadQuery<AppQuery>(
    graphql`
      query AppQuery {
        allFilms {
          films {
            id
            title
            director
          }
        }
      }
    `,
    {}
  );

  const films = data?.allFilms?.films?.filter((film) => film != null);

  return (
    <div>
      <h1>Star Wars Films</h1>
      {films?.map((film) => (
        <li key={film.id}>
          <b>{film.title}</b>: directed by <i>{film.director}</i>
        </li>
      ))}
    </div>
  );
}

Compile and run your app

All that’s left is to run the Relay compiler and start your app!

npx relay-compiler
npm run dev

You should now be able to open your app in a browser: http://localhost:5173/