DOCSEARCHbyAlgolia
Submit Docs

Relay Examples

repository·main·Indexed 22 days ago

https://github.com/relayjs/relay-examples

A collection of reference implementations and example applications demonstrating Relay best practices and architectural patterns. Includes examples for Next.js 13 React Server Components (RSC) using loadSerializableQuery, data-driven dependencies for dynamic module loading, and full-stack applications like a GitHub Issues clone (issue-tracker), a Newsfeed app, and a TodoMVC implementation using GraphQL Yoga and Vite.

Tokens
11K
Snippets
41
Records
51
Agent score
78%

What's inside relay-examples

  1. Overview of Relay Examples

    main
    This repository is a collection of example applications designed to demonstrate various ways to use Relay. It includes implementations of different application types, such as issue trackers, newsfeeds, and todo lists, to showcase Relay's capabilities in real-world scenarios.

  2. Understand the Newsfeed project structure

    main

    The project follows a standard React/TypeScript structure:

    • src/: Main source code directory.
    • src/components/: React components used in the application.
    • src/index.tsx: The application entry point.
    • webpack.config.js: Webpack configuration.
    • tsconfig.json: TypeScript configuration.
    • .prettierrc.json: Prettier configuration.
    • .eslintrc.json: ESLint configuration.

  3. Configure GraphQL Schema for Data-Driven Dependencies

    main

    To support dynamic module loading, your GraphQL schema must include specific fields and types to communicate module requirements from the server to the client:

    1. Type or Interface requirement: Must include a js field with the following signature:
      • js(module: String!, id: String): JSDependency
    2. Scalar Type: A scalar type named JSDependency must be defined.

  4. How the issue-tracker app uses Relay and React features

    main

    The issue-tracker app is designed to demonstrate how Relay Hooks integrate with modern React features. Key architectural patterns include:

    • Render-as-you-fetch: The app implements this pattern using React Suspense for data-fetching. During route transitions, the app loads both code and data for new routes in parallel.
    • Relay Hooks: Uses useFragment() and related hooks to colocate data dependencies directly within the components that need them.
    • Concurrent Mode & Suspense: Uses useTransition() for route transitions, allowing the app to continue showing the previous route while the next route's data and code are being prepared.
    • Custom Router Integration: Because React Router does not yet natively support data preloading for routes, this app uses React Router primitives (history and react-router-config) to implement custom preloading of code and data.

  5. Understand the Relay TodoMVC architecture

    main

    The Relay TodoMVC application uses a full-stack architecture composed of the following layers:

    • Schema: The source of truth is defined using Grats annotations within the data/ directory. TypeScript types drive the schema generation.
    • Server: A GraphQL Yoga server running on port 3000.
    • Client: A React application using Relay for data fetching, bundled with Vite.

  6. Understand Data-Driven Dependencies in Relay

    main
    Data-Driven Dependencies allow you to exclude specific React components and Relay artifacts from the initial JavaScript bundle. Instead of loading everything upfront, these modules are loaded dynamically on the client only when the server determines that a specific GraphQL type is about to be rendered. This is achieved through a combination of GraphQL schema extensions, a custom Relay operationLoader, and a specialized React component called MatchContainer.

  7. How to fetch Relay queries in Next.js 13 React Server Components

    main

    This example demonstrates a pattern for fetching Relay queries within Next.js 13 React Server Components (RSC) and hydrating them on the client.

    1. Server-side Fetching: Use loadSerializableQuery within an async page.tsx (the RSC) to fetch the root query data. This method returns serialized query results.
    2. Data Transfer: Pass these serialized results from the RSC to a Root Client Component (e.g., MainViewClientComponent) via props.
    3. Client-side Hydration: In the Client Component, use the useSerializablePreloadedQuery hook to convert the serialized results into a Relay PreloadedQuery object.
    4. Rendering: Pass the PreloadedQuery to a Root Relay Component, which uses the usePreloadedQuery hook to render the data.
    flowchart LR;
    RSC(Root React Server Component)--Serialized Query Results-->RCC(Root Client Component);
    RCC(Root Client Component)--Preloaded Query-->RRC(Root Relay Component);

  10. Setup the issue-tracker example app

    main

    To run the GitHub Issues clone example, follow these steps to clone the repository, install dependencies, and configure the environment.

    1. Clone the repository:

      git clone git@github.com:relayjs/relay-examples.git
cd relay-examples/issue-tracker

    2. Install dependencies: Using npm:

      npm install

      Using yarn:

      yarn

    3. Install Watchman: Watchman is required as a file watching service.

      • macOS/Linux (Homebrew): brew install watchman
      • Windows (Chocolatey): choco install watchman

    4. Configure GitHub Authentication: The app queries GitHub's public GraphQL API. You must provide a GitHub personal access token with at least the repo scope.

      • Create a file named .env.local in the issue-tracker/ directory.
      • Add the following line, replacing <TOKEN> with your actual token: REACT_APP_GITHUB_AUTH_TOKEN=<TOKEN>
    git clone git@github.com:relayjs/relay-examples.git
cd relay-examples/issue-tracker
npm install
# Create issue-tracker/.env.local with:
# REACT_APP_GITHUB_AUTH_TOKEN=<TOKEN>