DOCSEARCHbyAlgolia
Submit Docs

Relay Documentation

website·Indexed 40 days ago

https://relay.dev/

A powerful GraphQL client for React designed for high performance. This documentation covers the Relay runtime, compiler architecture, and API references for hooks such as usePreloadedQuery, useFragment, and usePaginationFragment. It includes guides on Relay Resolvers, Server 3D, data-driven dependencies, and the GraphQL server specification for connection and object identification.

Tokens
909.7K
Snippets
3.5K
Records
5.6K
Agent score
56%

What's inside Relay

  1. Overview of Relay data management features

    v18.0.0

    Relay is a data management library for React that uses GraphQL to provide high-performance data fetching and updates. Key capabilities include:

    • Declarative Data & Co-location: Components declare their own data needs, which Relay combines into efficient, pre-loadable queries.
    • Performance Optimizations: Includes pre-fetching (analyzing code to fetch queries before execution) and a JIT-friendly runtime for fast data processing.
    • State Management: Maintains a normalized data store to ensure consistent updates across components observing the same data.
    • Advanced UI Patterns: Built-in support for loading states, pagination, refetching, optimistic updates, and rollbacks.
    • Streaming: Supports declaratively deferring parts of a query to progressively re-render the UI as data streams in.
    • Developer Tooling: Provides type safety via generated definitions and full autocompletion/go-to-definition for GraphQL schemas.

  2. Overview of Relay data management features

    v17.0.0

    Relay is a data management library for React that uses GraphQL to provide high-performance data fetching and updates. Key capabilities include:

    • Declarative Data & Co-location: Components declare their own data needs; Relay aggregates these into efficient queries, ensuring queries update automatically when components are reused.
    • Performance Optimizations: Supports pre-fetching (analyzing code to fetch data before code execution), a JIT-friendly hyper-optimized runtime, and streaming/deferred data for progressive UI rendering.
    • State Management: Maintains a normalized data store to keep components in sync and provides a unified API for both server data and local client state.
    • Developer Experience: Offers static type safety (via generated type definitions), autocompletion, and go-to-definition based on the GraphQL schema.
    • Built-in UI Patterns: Simplifies the implementation of loading states, pagination, refetching, optimistic updates, and rollbacks.

  3. Overview of Relay Runtime Architecture

    The Relay runtime is a high-performance GraphQL client designed for large, complex applications. It serves as a foundation for higher-level APIs (like React/Relay) and provides several core capabilities:

    • A normalized, in-memory object graph cache.
    • Optimized write operations for updating the cache via queries, mutations, and subscriptions.
    • Mechanisms for reading data and subscribing to updates.
    • Garbage collection to evict unreferenced cache entries.
    • Interception of data for synthesis or merging (enabling pagination schemes).
    • Optimistic updates for mutations.
    • Support for live queries and subscriptions.
    • Primitives for offline and persisted caching.

  4. Overview of Relay Refetchable Fragments

    v15.0.0

    Refetchable fragments allow developers to update a specific subset of data in response to user input (e.g., search filters) without refetching the entire root query. This prevents unnecessary data transfer and avoids disrupting unrelated parts of the UI.

    When a fragment is marked as refetchable, the Relay compiler generates a separate, synthetic query specifically for that fragment. The data is initially fetched as part of the larger parent query, but subsequent updates use the generated refetch query.

  5. Overview of Relay testing tools

    v16.0.0

    Testing Relay components can be challenging due to the data fetching layer. Relay provides two primary tools to simplify this process for unit and integration tests (e.g., using Jest):

    1. createMockEnvironment(options): Creates a RelayMockEnvironment which implements the Relay Environment Interface and adds a mock layer to resolve, reject, and control the flow of queries, mutations, and subscriptions.
    2. MockPayloadGenerator and the @relay_test_operation directive: Automates the generation of dummy data based on the operation's selection set, reducing the need to manually maintain large mock objects.

  6. Overview of Relay testing tools

    v18.0.0
    Testing Relay components can be challenging due to the data fetching layer. Relay provides two primary modules to simplify this process: createMockEnvironment, which creates a test-specific environment to control request/response flows, and MockPayloadGenerator (used with the @relay_test_operation directive), which automates the generation of mock data to reduce the boilerplate associated with manual mock objects.

  7. Overview of Relay Refetchable Fragments

    v18.0.0

    Refetchable fragments allow a developer to update a specific subset of data in response to user input (e.g., search filters) without refetching the entire root query. This prevents unnecessary data transfer and avoids disrupting unrelated parts of the UI.

    When a fragment is marked as refetchable, the Relay compiler generates a separate, synthetic query specifically for that fragment. The data is initially fetched as part of the larger parent query, but subsequent updates use the generated refetch query.

  8. Overview of Relay Typesafe Updaters

    v15.0.0
    Typesafe updaters provide a typesafe and ergonomic alternative to legacy APIs for imperatively updating data in the Relay store. Instead of using verbose, non-typesafe methods, developers use updatable queries or fragments to create an 'updatable proxy'. Mutating this proxy via setters (e.g., updatableData.name = "Godzilla") triggers the underlying store updates with full type safety. These APIs may be labeled with an _EXPERIMENTAL suffix, but are recommended for use in new code.

  9. Overview of Relay Data Driven Dependencies (3D)

    v19.0.0
    Data Driven Dependencies (3D) is a Relay feature that enables dynamic loading of components based on the data being rendered. It improves application performance by reducing the JavaScript bundle size, as only the components required for the specific data present on the page are downloaded. It also simplifies complex rendering logic by removing the need for extensive conditional logic when mapping data to multiple possible components.

  10. Overview of Relay GraphQL client features

    v20.0.0

    Relay is a GraphQL client for React designed for high performance, scalability, and maintainability. It allows components to declaratively define their own data requirements, which Relay then aggregates into optimized queries. Key capabilities include:

    • Declarative Data Fetching: Components declare needed data; Relay generates optimal queries for the specific surface.
    • Composability: Components can be moved or reused without manually updating parent queries.
    • Pre-fetching: Generated queries enable data fetching to begin before the application code is downloaded or executed.
    • Built-in UI Patterns: Native support for loading states, pagination, refetching, optimistic updates, and rollbacks.
    • Normalized State Management: Maintains a normalized data store to ensure all components observing the same data remain synchronized.
    • Static Type Safety: Automatically generates TypeScript types for GraphQL snippets to catch errors at compile time.
    • Streaming and Deferred Data: Supports declarative deferring of query parts, allowing the UI to re-render progressively as data streams in.
    • Developer Tooling: Provides editor support for autocompletion and go-to-definition based on the GraphQL schema.

  11. Overview of Relay Resolvers

    Relay Resolvers allow developers to augment a GraphQL graph with values known only to the client. This enables the schematization of client state (such as data from client-side stores or derived data) using the same patterns as server state. This provides a unified data access API, global memoization with garbage collection, reactive recomputation, and efficient UI updates.

    Common use cases include:

    • User-Created Data: Complex form state or data that must outlive a specific component tree.
    • Client-Side Databases: Data from IndexedDB, localStorage, or SQLite.
    • Third-Party APIs: Data fetched directly by the client from external providers.
    • Encrypted Data: End-to-end encrypted data that is opaque to the server.
    • Legacy Data Stores: Exposing data from older layers (e.g., Redux) to maintain sync during migration.

  12. Overview of Relay testing tools

    v15.0.0

    Testing Relay components often requires managing a complex data fetching layer. Relay provides two primary tools to simplify this process for unit and integration tests (e.g., using Jest):

    1. createMockEnvironment(options): Creates a RelayMockEnvironment which implements the Relay Environment Interface and adds a mock layer to resolve, reject, and control the flow of GraphQL operations.
    2. MockPayloadGenerator and the @relay_test_operation directive: Automates the generation of dummy data for GraphQL selections, reducing the need to manually maintain large mock response objects.