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:

Core Philosophy

These principles are the foundation of every decision below. When in doubt, refer back to them.

• Co-location: Each component declares its own data requirements via a GraphQL fragment, right next to the rendering code. Data needs travel with the component, not separately.
• Data masking: A component can only access the fields it explicitly selected in its own fragment. Parents cannot see child fragment data, and vice versa. This prevents implicit coupling between components.
• Composition: Fragments compose into parent fragments and ultimately into queries, forming a tree that mirrors the component tree. The compiler flattens this into a single network request per query.
• Render-as-you-fetch: Start fetching data before the component that needs it renders. This avoids sequential request waterfalls.
• Normalized store: Relay maintains a flat, ID-keyed cache. When a mutation returns updated data, every component reading that data re-renders automatically. You do not need to manually propagate changes.

Compiler Workflow

Relay uses an ahead-of-time compiler that reads graphql tagged template literals in your code and generates runtime artifacts and TypeScript/Flow types.

Finding the config

The compiler looks for its config in these locations (checked in order):

• relay.config.{json,js,mjs,ts} in the project root
• A "relay" key in package.json

See <llm-docs>/getting-started/compiler-config.mdx for the full config schema. You can also emit a JSON Schema for the config by running npx relay-compiler config-json-schema.

Running the compiler

Run npx relay-compiler after any change to the contents of a graphql tagged template literal or the docblock of a Relay Resolver. Some projects add this as

…