facebook/relay: a GraphQL client where queries live next to the components that need them

The problem Relay solves: query strings that drift away from the components using them

In a plain React app talking to GraphQL, the query usually lives in a file far from the component that renders the result. Someone adds a field to the UI, someone else edits the query, and the two changes are reviewed separately. Relay inverts that. The README describes the model as colocation: "Queries live next to the views that rely on them, so you can easily reason about your app." A component declares a fragment, and the framework decides how and when to fetch it.

The second half of the pitch is aggregation. Rather than one request per component, Relay collects the fragments needed for a rendered subtree and issues a single network request for exactly those fields. That matters most in deep trees where each level would otherwise fire its own call. The README also lists declarative data requirements and mutations with "automatic data consistency, optimistic updates, and error handling" as the other two pillars.

The audience is narrow and specific. You need a GraphQL server, a React application, and a build pipeline you control, because Relay is not a runtime-only library. Teams that treat their GraphQL schema as a contract and want the compiler to enforce it are the ones this fits.

How the compiler turns fragments into one request

Relay ships a compiler in addition to a runtime. The repository layout makes this visible: there is a top-level compiler/ directory alongside packages/, and the root package.json declares a build script that runs gulp dist. The published packages are built from this repository rather than consumed as source.

The flow works like this. You write GraphQL fragments and queries inside your JavaScript files, marked so the compiler can find them. The compiler reads your GraphQL schema, validates every fragment against it, and generates artifacts that the runtime consumes. At render time the runtime walks the components being rendered, collects their fragment references, and merges them into a single query for the server. The schema is therefore a build-time input, not just a server-side concern. If a field does not exist, the build fails rather than the request.

This is the part that surprises people coming from other GraphQL clients. Apollo-style clients typically let you write a query string and send it; Relay wants to know your schema before your app runs. That trade buys type safety and the aggregation behaviour, and it costs you a build step that has to be wired correctly in development, in CI, and in whatever bundler you use.

Installing Relay and running the TodoMVC example

The README does not give a bare npm install line for a new project. It points to the documentation site for that: "See how to use Relay in your own project" links to relay.dev/docs/en/introduction-to-relay. What the README does give is a complete worked example in the separate relay-examples repository, an implementation of TodoMVC. That is the fastest way to see the compiler and runtime working together.

Clone the examples and move into the todo directory:

git clone https://github.com/relayjs/relay-examples.git
cd relay-examples/todo

Install dependencies, then run the two generation steps before starting the dev server:

yarn
yarn grats
yarn relay
yarn dev

The README states that you then point your browser at http://localhost:5173. Note the order: yarn grats and yarn relay are separate commands, and both run before yarn dev. The relay step is the compiler pass described above; if you skip it, the generated artifacts the runtime imports will not exist. The grats step is specific to this example's schema tooling, so do not assume every Relay project needs the same command sequence.

For your own project, the root package.json in the main repository shows the shape of the maintainers' own workflow, including npm run build (gulp dist), npm run typecheck (flow check), and npm run typecheck:ts for the TypeScript configuration at packages/relay-runtime/tsconfig.json. Those are the repository's internal scripts, not a template for an application, but they indicate that a Relay codebase is expected to be type-checked in both Flow and TypeScript configurations.

The compiler is a hard dependency, and that is the main constraint

The clearest limitation is structural. Relay is not something you drop into an existing app and start using incrementally on one screen without touching the build. The compiler needs your schema, and the runtime needs the artifacts the compiler produces. If your team cannot add and maintain that step, Relay is the wrong tool regardless of how well the data-fetching model fits.

There is a second boundary that the README does not address at all: it says nothing about offline behaviour, nothing about cache persistence across sessions, and nothing about rollback or migration between major versions. The release history shows v21.0.0 in May 2026 and v21.0.1 later that month, following v20.1.1 in August 2025. A major version bump between those lines means an upgrade path exists, but the README does not document one, so treat the release notes and the documentation site as the source for that work rather than this file.

Finally, the repository's primary language is listed as Rust. That is a fact about where the compiler work happens, not about what you write. Your application code stays JavaScript or TypeScript; the Rust portion is internal to the toolchain. Teams that expect to read and patch the compiler itself should know they would be working in Rust.

Relay against a plain query-string client

The obvious alternative is a runtime-only GraphQL client such as Apollo Client, where you write query strings and the library sends them. The difference in approach is where validation happens. A runtime client discovers a bad field when the server rejects the request or returns an error; Relay discovers it when the compiler runs, before the app is built. That shifts a class of bugs left, at the cost of the build step.

The second difference is aggregation. With a runtime client, combining the needs of several components into one request is something you arrange yourself, usually by lifting the query to a parent. Relay does that merge automatically from the fragments in the rendered tree. If your component tree is shallow and your queries are few, the merge buys you little and the compiler buys you a build dependency.

The third difference is colocation as a convention. Nothing stops you from putting query strings next to components with a runtime client, but nothing enforces it either. Relay's compiler enforces the relationship because a fragment that is not referenced by a rendered component contributes nothing.

Maintenance, licensing and what a version bump costs

The repository is not archived, and the last push was on 2026-09-19, two days before this writing. The most recent release in the list is v21.0.1 from 2026-05-27, preceded by v21.0.0 on 2026-05-18 and v20.1.1 on 2025-08-06. The gap between v20.1.1 and v21.0.0 is roughly nine months, which is worth knowing if you plan release cadence around upstream.

Licensing is MIT, stated in the README and in the root package.json ("license": "MIT"). MIT permits commercial use and modification with the licence and copyright notice retained. That is a description of the licence text, not legal advice; if your organisation has specific obligations around attribution or dependency review, run it past whoever handles that.

Upgrade cost is the practical concern. Because the compiler validates against your schema at build time, a major Relay release can surface errors in your fragments that a runtime-only client would never raise. Budget for a branch where you bump the version, run the compiler, and work through whatever it reports. The README does not describe this process, so the release notes are where you would confirm what changed.

Editorial conclusion

Adopt Relay when your backend already speaks GraphQL, your component tree is large enough that hand-written query strings have become unmanageable, and your team will run the compiler in CI. Do not adopt it if your API is REST, if you cannot add a build step, or if you expect to write queries by hand at runtime. Before committing, verify two things: that your schema passes the compiler without errors, and that your build pipeline runs the relay step after every change to a fragment. The repository's own example, relay-examples/todo, is the fastest way to see both.

Frequently asked questions

Official sources

1. facebook/relay on GitHub
2. License: MIT
3. Project website
4. README
5. Releases