# Relay — Declarative GraphQL Data Fetching for React

> Relay is a JavaScript framework by Meta for building data-driven React applications powered by GraphQL. It handles data fetching, caching, and optimistic updates with a compiler-driven approach.

## Install

Save in your project root:

# Relay — Declarative GraphQL Data Fetching for React

## Quick Use
```bash
npm install react-relay relay-runtime relay-compiler babel-plugin-relay
```
```javascript
// UserComponent.js
import { graphql, useFragment } from 'react-relay';
const UserComponent = ({ userRef }) => {
  const data = useFragment(
    graphql`fragment UserComponent_user on User { name avatar }`,
    userRef
  );
  return <div>{data.name}</div>;
};
```

## Introduction
Relay is a GraphQL client framework built by Meta (Facebook) that tightly integrates with React. It uses a compiler to analyze GraphQL fragments at build time, generating optimized queries and type-safe artifacts. This approach eliminates overfetching, enables automatic data consistency, and scales to applications with thousands of components.

## What Relay Does
- Co-locates GraphQL fragment declarations with the React components that use them
- Compiles fragments at build time into optimized queries with deduplication
- Maintains a normalized client-side cache that automatically updates across components
- Supports pagination, refetching, and mutations with built-in hooks
- Generates TypeScript or Flow types from GraphQL schemas for type safety

## Architecture Overview
The Relay compiler reads GraphQL tagged template literals from source files, validates them against the schema, and generates query artifacts. At runtime, Relay's store holds a normalized graph of records keyed by ID and typename. When a mutation or subscription updates a record, every component observing that record re-renders. The compiler also splits queries across code-split boundaries, fetching data in parallel with component code.

## Self-Hosting & Configuration
- Add `relay-compiler`, `babel-plugin-relay`, and `react-relay` to your project
- Point the compiler at your GraphQL schema via `relay.config.js`
- Run `relay-compiler --watch` during development for continuous artifact generation
- Configure the Relay Environment with your network layer (fetch function) and store
- Works with any GraphQL server that supports the Relay cursor-based pagination spec

## Key Features
- Compiler-driven approach that catches GraphQL errors at build time, not runtime
- Normalized store that ensures data consistency across the entire component tree
- Automatic garbage collection of unreferenced data to bound memory usage
- Built-in support for @defer, @stream, and live queries for real-time data
- Declarative pagination via useFragment and usePaginationFragment hooks

## Comparison with Similar Tools
- **Apollo Client** — more flexible but relies on runtime query processing; Relay optimizes at compile time
- **urql** — lightweight and extensible; Relay offers stronger guarantees for large-scale apps
- **TanStack Query** — REST-first data fetching; Relay is purpose-built for GraphQL
- **SWR** — generic data fetching hooks; Relay provides a normalized GraphQL-aware cache
- **Grafbase** — managed GraphQL backend; Relay is a client-side framework

## FAQ
**Q: Does Relay require a specific GraphQL server?**
A: No, but your server should support the Relay connection spec (edges/nodes) for pagination and globally unique IDs for the normalized store.

**Q: Is the Relay compiler fast?**
A: Yes. The compiler is written in Rust and processes large codebases incrementally in watch mode.

**Q: Can I use Relay with TypeScript?**
A: Yes. The compiler generates TypeScript types for all fragments and queries.

**Q: Is Relay used in production?**
A: Meta uses Relay across Facebook, Instagram, and other products serving billions of users.

## Sources
- https://github.com/facebook/relay
- https://relay.dev/docs/

---
Source: https://tokrepo.com/en/workflows/6738ecde-44f8-11f1-9bc6-00163e2b0d79
Author: AI Open Source