Improved React APIs for Relay

This article was written in collaboration with Juan Tejada, a software engineer at Facebook.

Today we’re excited to release Relay Hooks: a set of new, more developer-friendly relay APIs built with React Hooks.

However, new does not mean untested: The newly written is fully supported by relay hooks. These APIs have been the recommended way to use Relay on Facebook since mid-2019. The Hooks APIs were developed in close collaboration with the React Core team with the future of React in mind and have proven to be popular, stable and successful.

Since Relay was first developed, we’ve learned a few things about building maintainable, data-driven applications, and we’ve combined these best practices in a new guide and our updated documents. While we still have a long way to go before getting started with Relay is as easy as we’d like, we believe this release will vastly improve the Relay development experience.

The new APIs are fully compatible with the existing APIs. We recommend writing new code with relay hooks. Migrating existing containers to the new APIs is optional, and container-based code will still work.

What is relay?

Relay is a JavaScript framework for retrieving and managing GraphQL data in React applications with a focus on maintainability, type safety, and runtime performance.

Relay achieves this by combining declarative data retrieval and a static build step. When data is fetched declaratively, components declare what data they need, and Relay works out how to fetch it efficiently. During the static build step, Relay validates and optimizes queries and precomputes artifacts for faster runtime performance.

What are relay hooks?

Relay Hooks is a set of new hook-based APIs for using Relay with React that improve on the existing container-based APIs.

The Hooks APIs provide an improved developer experience, especially for re-fetching and pagination. improved type security with greater coverage; Use the compiler functions to automate error-prone tasks, e.g. B. the generation of refetch queries. and are fully compatible with React Strict Mode.

In addition, the new APIs allow developers to display content to users faster by starting to fetch data before a component is rendered. Pre-fetching data in this way is not possible with the container-based APIs.

Most of all, the new APIs are simple. Consider this example of pagination:

If you’re interested, here’s what this example would have looked like if it had been written using the old container-based APIs.

Where to go next

For more information on the new APIs, see the announcement post on If you’d like to try relay hooks, check out the getting started guide, migration guide, or guided tour.

A detailed plan for upcoming releases can be found in this issue of GitHub.


This release wasn’t just an effort by the core Relay team. We are deeply indebted to the many open source contributors who have helped. We’d also like to thank the React core team for working closely together in developing these new APIs. Additionally, we would like to thank Joe Savona, Lauren Tan, and Dan Abramov for their generous help handling this announcement.

Comments are closed.