# relay-best-practices

> Claude/Codex skill by [@facebook](https://omgskills.com/library/facebook/index.md) · 19k stars · Updated 2026-09-11

Best practices for writing idiomatic Relay code. ALWAYS use this skill when writing or modifying React components that use Relay for data fetching. Covers fragments, queries, mutations, pagination, and common anti-patterns. Use when you see \`useFragment\`, \`useLazyLoadQuery\`, \`usePreloadedQuery\`, \`useMutation\`, \`usePaginationFragment\`, \`graphql\` template literals, \`react-relay\` imports, or \`\_\_generated\_\_/\*.graphql\` files. Also use when asked to explain Relay concepts, debug Relay issues, or review Relay code.

## Install

```sh
git clone https://github.com/facebook/relay /tmp/relay && ln -s /tmp/relay/skills/relay-best-practices ~/.claude/skills/relay-best-practices
```

## From README

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 nodemodules/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 ( /). Read the relevant page before writing Relay code.

## Links

- HTML page: https://omgskills.com/skills/facebook/relay/relay-best-practices/
- GitHub: https://github.com/facebook/relay
- Author: [@facebook](https://omgskills.com/library/facebook/index.md)

## More skills by this author

- [extract-errors](https://omgskills.com/skills/facebook/react/extract-errors/index.md) — Used when adding new error messages to React, or seeing "unknown error code" warnings.
   - [@facebook](https://omgskills.com/library/facebook/index.md) · 250k stars
- [feature-flags](https://omgskills.com/skills/facebook/react/feature-flags/index.md) — Used when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test...
   - [@facebook](https://omgskills.com/library/facebook/index.md) · 248k stars
- [flags](https://omgskills.com/skills/facebook/react/flags/index.md) — Used when you need to check feature flag states, compare channels, or debug why a feature behaves differently across...
   - [@facebook](https://omgskills.com/library/facebook/index.md) · 248k stars