Introducing Relay Hooks: Improved React APIs for Relay

This article was written in collaboration with Juan Tejada, a Software Engineer at Facebook.

Today, we are excited to release Relay Hooks: a set of new, more developer-friendly Relay APIs built using React Hooks.

But new does not mean untested: the rewritten Facebook.com is entirely powered by Relay Hooks, and these APIs have been the recommended way to use Relay at Facebook since mid-2019. The Hooks APIs were written in close collaboration with the React Core team, with the future of React in mind, and have proved themselves popular, stable and successful.

We’ve learned quite a few things about building maintainable, data-driven applications since we first developed Relay, and have distilled these best practices into a new guided tour and our updated docs. Though we still have a ways to go before getting started with Relay is as easy as we’d like, we believe this release substantially improves the Relay developer experience.

The new APIs are fully compatible with the existing APIs. We recommend writing any new code using Relay Hooks. Migrating existing containers to the new APIs is optional, and container-based code will continue to work.

What is Relay?

Relay is a JavaScript framework for fetching and managing GraphQL data in React applications that emphasizes maintainability, type safety and runtime performance.

Relay achieves this by combining declarative data fetching and a static build step. With declarative data fetching, components declare what data they need, and Relay figures out how to efficiently fetch it. During the static build step, Relay validates and optimizes queries, and pre-computes artifacts to achieve faster runtime performance.

What are Relay Hooks?

Relay Hooks is a set of new Hooks-based APIs for using Relay with React that improves upon the existing container-based APIs.

The Hooks APIs provide an improved developer experience, especially for refetching and pagination; have improved type safety with greater coverage; take advantage of compiler features to automate error-prone tasks, such as generating refetch queries; and are fully compatible with React Strict Mode.

In addition, the new APIs allow developers to more quickly show content to users by starting to fetch data before a component renders. Prefetching data in this way is not possible with the container-based APIs.

But most importantly, the new APIs are just simpler. Consider this example of pagination:

If you’re interested, you can see how this example would have looked if written using the old, container-based APIs here.

Where to go next

You can find more information about the new APIs in the announcement post on relay.dev. If you’re interested in trying out Relay Hooks, check out the getting started guide, the migration guide or the guided tour.

For a detailed plan of upcoming releases see this GitHub issue.

Acknowledgments

This release wasn’t just an effort by the Relay core team. We’re heavily indebted to the many open source contributors who have helped. We’d also like to thank the React core team for working closely with us in designing these new APIs. In addition, we’d like to thank Joe Savona, Lauren Tan and Dan Abramov for their generous help editing this announcement.

To learn more about Facebook Open Source, visit our open source site, subscribe to our YouTube channel, or follow us on Twitter and Facebook.