Relay Best Practices

Relay is a GraphQL client for React that enforces colocated, composable, and type-safe data fetching. Its core insight is that each component should declare exactly what data it needs via GraphQL fragments, and Relay handles the rest — fetching, caching, consistency, and updates.

This skill provides opinionated guidance on which patterns to prefer. For detailed API documentation, read the relevant page from the doc map below.

Documentation

Relay ships LLM-friendly docs in node_modules/relay-runtime/llm-docs/ (available after v20.1.1). For older versions, fetch the same files from https://raw.githubusercontent.com/facebook/relay/main/website/docs/.

Paths below are relative to this directory (<llm-docs>/). Read the relevant page before writing Relay code. Key docs: