Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RelayEnvironmentProvider
✓ import { RelayEnvironmentProvider } from 'react-relay'
✗ const { RelayEnvironmentProvider } = require('react-relay')
Provides the Relay environment to the React component tree. Primarily used with ESM imports.
useLazyLoadQuery
✓ import { useLazyLoadQuery } from 'react-relay'
✗ import { useQuery } 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.
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>
);
}
relay --version
Debug
Known issues
breakingSince 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.fixAdd `@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.
affects: >=19.0.0
breakingRelay 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.fixReview 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.
affects: >=17.0.0
breakingIn 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`.fixUpdate your `relay.config.js` (or equivalent) to change `customScalars: { ... }` to `customScalarTypes: { ... }`. affects: >=16.2.0 <17.0.0
gotchaRelay 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.fixThoroughly 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.
affects: >=18.1.0
gotchaThe `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.fixUpgrade `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.
affects: >=20.0.0
Errors
Common errors & fixes
Invariant Violation: Relay: Expected `RelayEnvironmentProvider` to be rendered higher in the tree.
The RelayEnvironmentProvider component, which supplies the Relay `Environment` to all hooks and components, is not rendered above the components trying to use Relay.
fixEnsure 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.
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.
fixEnsure 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.
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.
fixEnsure 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`.
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.
fixVerify 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.
Audit
Dependencies
reactrequiredPeer dependency for React application integration.