Relay Modern

# Runtime dependencies
npm install relay-runtime react-relay

# Dev dependencies
npm install -D relay-compiler babel-plugin-relay graphql

# TypeScript types
npm install -D @types/relay-runtime @types/react-relay

relay.config.json:

{
  "src": "./src",
  "schema": "./schema.graphql",
  "language": "typescript"
}

Compiler commands:

npx relay-compiler           # Build once
npx relay-compiler --watch   # Watch mode (needs Watchman)

import { Environment, Network, Store, RecordSource } from "relay-runtime";
import type { FetchFunction } from "relay-runtime";

const fetchFn: FetchFunction = async (request, variables) => {
  const resp = await fetch("/graphql", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: request.text,
      variables,
    }),
  });
  return await resp.json();
};

export const environment = new Environment({
  network: Network.create(fetchFn),
  store: new Store(new RecordSource()),
});

import { RelayEnvironmentProvider } from "react-relay";
import { environment } from "./environment";

function App() {
  return (
    <RelayEnvironmentProvider environment={environment}>
      <MainContent />
    </RelayEnvironmentProvider>
  );
}

// vite.config.ts
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react({ babel: { plugins: ["relay"] } })],
});

import { graphql, useFragment } from "react-relay";
import type { UserCard_user$key } from "./__generated__/UserCard_user.graphql";

type Props = { user: UserCard_user$key };

function UserCard({ user }: Props) {
  const data = useFragment(
    graphql`
      fragment UserCard_user on User {
        name
        avatar {
          uri
        }
      }
    `,
    user,
  );

  return <div>{data.name}</div>;
}

Fragment naming: ComponentName_propName

# Parent query spreads child fragment
query UserPageQuery($id: ID!) {
  user(id: $id) {
    ...UserCard_user
    ...UserPosts_user
  }
}

# Child fragments compose further
fragment UserCard_user on User {
  name
  ...UserAvatar_user
}

fragment UserAvatar_user on User
@argumentDefinitions(size: { type: "Int", defaultValue: 100 }) {
  avatar(size: $size) {
    uri
  }
}

# Parent passes arguments
fragment UserCard_user on User {
  ...UserAvatar_user @arguments(size: 200)
}

import { graphql, usePreloadedQuery, loadQuery } from "react-relay";
import type { AppQuery } from "./__generated__/AppQuery.graphql";

const query = graphql`
  query AppQuery($id: ID!) {
    user(id: $id) {
      name
      ...UserCard_user
    }
  }
`;

// Preload early (router, event handler, etc.)
const queryRef = loadQuery(environment, query, { id: "4" });

// Read in component (suspends until ready)
function App({ queryRef }) {
  const data = usePreloadedQuery(query, queryRef);
  return <h1>{data.user?.name}</h1>;
}

⚠️ loadQuery refs must be .dispose()d when no longer needed.

import { useQueryLoader } from "react-relay";

function ProfileButton({ userId }) {
  const [queryRef, loadQuery] = useQueryLoader(ProfileQuery);

  return (
    <>
      <button onClick={() => loadQuery({ id: userId })}>View Profile</button>
      {queryRef && (
        <Suspense fallback={<Spinner />}>
          <ProfilePage queryRef={queryRef} />
        </Suspense>
      )}
    </>
  );
}

import { graphql, useLazyLoadQuery } from "react-relay";

function App() {
  const data = useLazyLoadQuery(
    graphql`
      query AppQuery($id: ID!) {
        user(id: $id) {
          name
        }
      }
    `,
    { id: "4" },
    { fetchPolicy: "store-or-network" },
  );
  return <h1>{data.user?.name}</h1>;
}

⚠️ Not recommended — fetches during render, causes waterfalls. Prefer usePreloadedQuery.

import { graphql, useMutation } from "react-relay";

const [commit, isInFlight] = useMutation(graphql`
  mutation LikeMutation($input: LikeInput!) {
    like(input: $input) {
      post {
        id
        likeCount
        viewerHasLiked
      }
    }
  }
`);

commit({
  variables: { input: { postId: "123" } },
  onCompleted: (response) => console.log("Done", response),
  onError: (error) => console.error(error),
});

commit({
  variables: { input: { postId: "123" } },
  optimisticResponse: {
    like: {
      post: {
        id: "123",
        likeCount: currentCount + 1,
        viewerHasLiked: true,
      },
    },
  },
});

import { ConnectionHandler } from "relay-runtime";

commit({
  variables: { input: { title: "New Post" } },
  updater: (store) => {
    // Get connection
    const conn = ConnectionHandler.getConnection(
      store.get(userId)!,
      "PostList_posts",
    );

    // Create and insert edge
    const newPost = store.getRootField("createPost")!.getLinkedRecord("post");
    const edge = ConnectionHandler.createEdge(
      store,
      conn!,
      newPost!,
      "PostEdge",
    );
    ConnectionHandler.insertEdgeAfter(conn!, edge);
  },
});

# Auto-delete record from store
mutation DeletePostMutation($id: ID!) {
  deletePost(id: $id) {
    deletedPostId @deleteRecord
  }
}

# Type-safe optimistic responses
mutation LikeMutation($input: LikeInput!)
  @raw_response_type {
  like(input: $input) { ... }
}

import { graphql, usePaginationFragment } from "react-relay";

const { data, loadNext, hasNext, isLoadingNext } = usePaginationFragment(
  graphql`
    fragment PostList_user on User
    @argumentDefinitions(
      count: { type: "Int", defaultValue: 10 }
      cursor: { type: "String" }
    )
    @refetchable(queryName: "PostListPaginationQuery") {
      posts(first: $count, after: $cursor) @connection(key: "PostList_posts") {
        edges {
          node {
            id
            title
          }
        }
      }
    }
  `,
  userRef,
);

return (
  <>
    {data.posts?.edges?.map((edge) => (
      <Post key={edge.node.id} post={edge.node} />
    ))}
    {hasNext && (
      <button onClick={() => loadNext(10)} disabled={isLoadingNext}>
        {isLoadingNext ? "Loading..." : "Load More"}
      </button>
    )}
  </>
);

@argumentDefinitions(          # Declare pagination args
  count: { type: "Int", defaultValue: 10 }
  cursor: { type: "String" }
)
@refetchable(queryName: "...")  # Auto-generate refetch query
@connection(key: "...")         # Mark as paginated connection

import { graphql, useRefetchableFragment } from "react-relay";

const [data, refetch] = useRefetchableFragment(
  graphql`
    fragment CommentBody_comment on Comment
    @refetchable(queryName: "CommentBodyRefetchQuery") {
      body(lang: $lang) {
        text
      }
    }
  `,
  commentRef,
);

<button onClick={() => refetch({ lang: "SPANISH" })}>Translate</button>;

// In updater functions
updater: (store) => {
  // Get records
  const record = store.get("id-123");
  const root = store.getRoot();
  const field = store.getRootField("createPost");

  // Read/write scalars
  record.getValue("name");
  record.setValue("New Name", "name");

  // Read/write linked records
  record.getLinkedRecord("author");
  record.setLinkedRecord(newAuthor, "author");

  // Read/write linked record lists
  record.getLinkedRecords("comments");
  record.setLinkedRecords(newComments, "comments");

  // Create/delete records
  store.create("new-id", "Post");
  store.delete("old-id");
};

import { ConnectionHandler } from "relay-runtime";

// Get connection
const conn = ConnectionHandler.getConnection(record, "FeedList_posts", {
  orderBy: "DATE",
});

// Add edge
const edge = ConnectionHandler.createEdge(store, conn, newNode, "PostEdge");
ConnectionHandler.insertEdgeAfter(conn, edge);
ConnectionHandler.insertEdgeBefore(conn, edge);

// Remove node
ConnectionHandler.deleteNode(conn, nodeId);