React Relay

Common errors

• Invariant Violation: Relay: Expected `RelayEnvironmentProvider` to be rendered higher in the tree.

  cause The RelayEnvironmentProvider component, which supplies the Relay `Environment` to all hooks and components, is not rendered above the components trying to use Relay.
  fix Ensure that `RelayEnvironmentProvider` is rendered at the root of your application or above any components that utilize Relay hooks or components. Provide it with a valid `environment` prop: `<RelayEnvironmentProvider environment={relayEnvironment}>`.

• Error: Cannot find module 'react-relay/lib/relay-runtime/RelayRuntime' or similar module not found errors.

  cause This typically indicates a CommonJS `require()` call trying to access an internal ESM-only module path, or a mismatch in module resolution in older Node.js/bundler environments with modern Relay versions.
  fix Ensure your project is configured for ESM imports where `react-relay` is used, especially in modern React applications. Use `import { ... } from 'react-relay'` syntax. If using an older bundler or Node.js, ensure correct transpilation and module resolution is in place, or consider upgrading your tooling.

• Invariant Violation: Relay: Expected all GraphQL fragments to be spread, got null or undefined.

  cause This error often occurs when a fragment reference passed to `useFragment` (or similar) is `null` or `undefined`, usually because of conditional rendering or data being unexpectedly missing.
  fix Ensure that the fragment reference you are passing to `useFragment` is always a valid object. Add null/undefined checks before rendering components that rely on `useFragment`, or use optional chaining if the fragment reference might legitimately be absent.

• Relay: Missing fragment data for field `myField` on object `MyType`.

  cause A component or hook (e.g., `useFragment`) tried to access a field within a fragment that was not included in the corresponding GraphQL query that fetched the data.
  fix Verify that the GraphQL query used to fetch the data explicitly includes all the fields required by the fragments that are being spread and consumed by child components. Ensure your `graphql` tags accurately reflect your data requirements.

Warnings

• breaking Since Relay v19.0.0, the `@alias` directive is now required on all fragments that are only conditionally fetched due to `@skip`/`@include` or fragment type conditions. This improves type safety and prevents runtime errors. You may opt out of this validation on a per-fragment basis if necessary.
  Fix: Add `@alias` directive to conditional fragments: `...MyFragment @alias(as: "aliasedFragment") on MyType` or configure your Relay compiler to opt-out of this validation for specific fragments.
• breaking Relay v17.0.0 introduced stricter, spec-compliant schema validation, including client schema extensions and Relay Resolvers. This may cause existing valid GraphQL schemas (from older versions) to fail compilation.
  Fix: Review and update your GraphQL schema to ensure it is fully spec-compliant. The compiler output will provide specific error messages. You can temporarily opt out of some validations via Relay compiler configuration, but it's recommended to fix the schema.
• breaking In Relay v16.2.0, the compiler configuration option `customScalars` was renamed to `customScalarTypes` for single-project configuration files. If you are using custom scalars, this change requires an update to your `relay.config.js`.
  Fix: Update your `relay.config.js` (or equivalent) to change `customScalars: { ... }` to `customScalarTypes: { ... }`.
• gotcha Relay Resolvers, which enable structured and type-safe client-side state management, became stable in v18.1.0. While powerful, incorrect usage or misconfiguration can lead to unexpected client-side data behavior or type mismatches if not properly defined in your client schema extensions.
  Fix: Thoroughly review the official Relay Resolvers documentation. Ensure your client schema extensions accurately define resolver types and fields, and that the resolver functions correctly transform or derive data.
• gotcha The `eslint-plugin-relay` package (Relay's ESLint plugin) was updated to v2.0.0 alongside Relay v20.0.0. This release includes compatibility updates and removes deprecated rules. If you use the ESLint plugin, an upgrade may be necessary, and some linting rules might change or require re-configuration.
  Fix: Upgrade `eslint-plugin-relay` to v2.0.0 or higher. Review the `eslint-plugin-relay` changelog for any removed or changed rules that may affect your codebase and update your ESLint configuration accordingly.

Install

• npm install react-relay npm
• yarn add react-relay yarn
• pnpm add react-relay pnpm

Imports

• RelayEnvironmentProvider
  wrong:

  const { RelayEnvironmentProvider } = require('react-relay')

  correct:

  import { RelayEnvironmentProvider } from 'react-relay'

  Provides the Relay environment to the React component tree. Primarily used with ESM imports.
• useLazyLoadQuery
  wrong:

  import { useQuery } from 'react-relay'

  correct:

  import { useLazyLoadQuery } from 'react-relay'

  This hook is for fetching a query's data on initial render (or component mount). Do not confuse with 'useQuery' from other GraphQL clients.
• useFragment

  import { useFragment } from 'react-relay'

  Used to read data from a fragment. Requires a `graphql` tag with the fragment definition.
• graphql

  import { graphql } from 'react-relay'

  This template tag is essential for defining GraphQL queries, mutations, subscriptions, and fragments for the Relay compiler.

Quickstart

This quickstart demonstrates setting up a basic Relay Environment, defining a GraphQL query, and using `useLazyLoadQuery` within a React component to fetch and display data, including Suspense for loading states. It connects to a public Star Wars API.

import React from 'react';
import { 
  RelayEnvironmentProvider, 
  loadQuery, 
  useLazyLoadQuery, 
  graphql 
} from 'react-relay';
import { 
  Environment, 
  Network, 
  RecordSource, 
  Store 
} from 'relay-runtime';

// 1. Define a Network Layer
const fetchGraphQL = async (text, variables) => {
  const response = await fetch('https://swapi-graphql.netlify.app/.netlify/functions/index', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: text, variables }),
  });
  return await response.json();
};

const network = Network.create(fetchGraphQL);

// 2. Create a Relay Store
const store = new Store(new RecordSource());

// 3. Create a Relay Environment
const environment = new Environment({
  network,
  store,
});

// 4. Define a Query
const AppQuery = graphql`
  query AppQuery {
    allFilms {
      films {
        title
        releaseDate
      }
    }
  }
`;

// 5. Pre-load the query for suspense (optional, but good practice)
const preloadedQuery = loadQuery(environment, AppQuery, {});

function FilmList() {
  const data = useLazyLoadQuery(AppQuery, {}, { fetchPolicy: 'store-or-network' });

  return (
    <div>
      <h1>Star Wars Films</h1>
      <ul>
        {data.allFilms?.films?.map((film, index) => (
          <li key={index}>{film?.title} (Released: {film?.releaseDate})</li>
        ))}
      </ul>
    </div>
  );
}

export default function AppRoot() {
  return (
    <RelayEnvironmentProvider environment={environment}>
      <React.Suspense fallback={<div>Loading...</div>}>
        <FilmList />
      </React.Suspense>
    </RelayEnvironmentProvider>
  );
}