relay-runtime 20.1.1 → 21.0.0

package/llm-docs/guides/testing-relay-with-preloaded-queries.mdx

@@ -0,0 +1,160 @@
+---
+id: testing-relay-with-preloaded-queries
+title: Testing Relay with Preloaded Queries
+slug: /guides/testing-relay-with-preloaded-queries/
+description: Relay guide to testing with preloaded queries
+keywords:
+- testing
+- preloaded
+- usePreloadedQuery
+- queueOperationResolver
+- queuePendingOperation
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+Components that use preloaded queries (`useQueryLoader` and `usePreloadedQuery` hooks) require slightly different and more convoluted test setup.
+
+In short, there are two steps that need to be performed **before rendering the component**
+
+1. Configure the query resolver to generate the response via `environment.mock.queueOperationResolver`
+2. Record a pending queue invocation via `environment.mock.queuePendingOperation`
+
+## Symptoms that something is wrong
+
+1. The test doesn't do what is expected from it.
+2. The query seems to be blocking instead of executing
+   1. E.g. the `Suspend` doesn't switch from "waiting" to "data loaded" state
+3. If you add the `console.log` before and after `usePreloadedQuery`, only the "before" call is hit
+
+## TL;DR
+
+```javascript
+const {RelayEnvironmentProvider} = require('react-relay');
+const {MockPayloadGenerator, createMockEnvironment} = require('relay-test-utils');
+const {act, render} = require('@testing-library/react');
+test("...", () => {
+  // arrange
+  const environment = createMockEnvironment();
+  environment.mock.queueOperationResolver(operation => {
+      return MockPayloadGenerator.generate(operation, {
+        CurrencyAmount() {
+          return {
+            formatted_amount: "1234$",
+          };
+        },
+      });
+    });
+  const query = YourComponentGraphQLQueryGoesHere; // can be the same, or just identical
+  const variables = {
+    // ACTUAL variables for the invocation goes here
+  };
+  environment.mock.queuePendingOperation(YourComponentGraphQLQuery, variables);
+
+ // act
+  const {getByTestId, ..otherStuffYouMightNeed} = render(
+    <RelayEnvironmentProvider environment={environment}>
+        <YourComponent data-testid="1234" {...componentPropsIfAny}/>
+    </RelayEnvironmentProvider>
+  );
+  // trigger the loading - click a button, emit an event, etc. or ...
+  act(() => jest.runAllImmediates()); // ... if loadQuery is in the useEffect()
+  // assert
+  // your assertions go here
+});
+```
+
+### Configure the query resolver to generate the response
+
+This is done via `environment.mock.queueOperationResolver(operation)` call, but getting it right might be tricky.
+
+The crux of this call is to return a mocked graphql result in a very particular format (as `MockResolvers` type, to be precise). This is done via a second parameter to `generate` - it is an object, whose keys are GraphQL types that we want to mock. (See [`mock-payload-generator`](../testing-relay-components/#mock-payload-generator-and-the-relay_test_operation-directive)).
+
+Continuing on the above example:
+
+```js
+return MockPayloadGenerator.generate(operation, {
+  CurrencyAmount() { // <-- the GraphQL type
+    return {
+      formatted_amount: "response_value" <-- CurrencyAmount fields, selected in the query
+    };
+  }
+});
+```
+The tricky thing here is to obtain the name of the GraphQL type and fields to return. This can be done in two ways:
+
+* Call `console.log(JSON.stringify(operation, null, 2))` and look for the `concreteType` that corresponds to what we want to mock. Then look at the sibling `selections` array, which describes the fields that are selected from that object.
+
+<FbInternalOnly>
+
+* This is somewhat intense - P139017123 is the output for [this query](https://fburl.com/diffusion/irqurgj9). Rule of thumb - one nested call in the query produces one nested object in the output.
+* Look up the type in the graphiql (bunnylol graphiql), then specify the fields listed on the query.
+
+:::note
+The type you need seems to be the type returned by the *innermost function call* (or calls, if you have multiple functions called in one query - see D23078476). This needs to be confirmed - in both example diffs the target types was also leafs.
+:::
+
+</FbInternalOnly>
+
+
+It is **possible** to return different data for different query variables via [Mock Resolver Context](../testing-relay-components/#mock-resolver-context). The query variables will be available on the `context.args`, but only to the *innermost function call* (for the query above, only `offer_ids` are available)
+
+```javascript
+CurrencyAmount(context) {
+  console.log(JSON.stringify(context, null, 2)); // <--
+  return { formatted_amount: mockResponse }
+}
+// <-- logs { ...snip..., "name": "subtotal_price_for_offers", args: { offer_ids: [...] } }
+```
+### Record a pending queue invocation
+
+This is more straightforward - it is done via a call to `environment.mock.queuePendingOperation(query, variables)`
+
+* `Query` needs to match the query issues by the component. Simplest (and most robust against query changes) is to export the query from the component module and use it in the test, but having an *identical* (but not the same) query works as well.
+* `variables` has to match the variables that will be used in this test invocation.
+   * Beware of nested objects and arrays - they are compared via `areEqual` ([invocation code](https://github.com/facebook/relay/blob/046f758c6b411608371d4cc2f0a594ced331864e/packages/relay-test-utils/RelayModernMockEnvironment.js#L233))
+      * Arrays are compared by values (not by reference), but the order of elements matter
+      * Nested objects - performs deep compare, order of keys is not relevant (this is not confirmed - please update this doc if you used a graphql query with "deep" structure*)*
+
+<FbInternalOnly>
+
+### Example diffs
+
+* [D23078476](https://internalfb.com/intern/diff/D23078476)
+* [D23101739](https://www.internalfb.com/diff/D23101739)
+
+</FbInternalOnly>
+
+## Troubleshooting
+
+* `console.log`, `console.log` everywhere! Recommended places:
+   * component: before and after `useQueryLoader, usePreloadedQuery, loadQuery`
+   * test: in `queueOperationResolver` callback
+   * library: in `RelayModernMockEnvironment.execute`, after the `const currentOperation = ...` call ([here](https://github.com/facebook/relay/blob/046f758c6b411608371d4cc2f0a594ced331864e/packages/relay-test-utils/RelayModernMockEnvironment.js#L230))
+* If `loadQuery` is not called - make sure to issue the triggering event. Depending on your component implementation it could be a user-action (like button click or key press), javascript event (via event emitter mechanisms) or a simple "delayed execution" with `useEffect`.
+   * The `useEffect` case is probably easiest to miss - make sure to call `act(() => jest.runAllImmediates())` **after** rendering the component
+* If "before" `usePreloadedQuery` is hit, but "after" is not - the query suspends. This entire guide is written to resolve it - you might want to re-read it. But most likely it is either:
+   * Used a different query - the query resolver would not be called, `currentOperation` will be `null`
+   * Query variables don't match - the query resolver would not be called, `currentOperation` will be `null` (make sure to inspect the `variables`).
+      * Also, make sure arrays are in the same order, if any (or better yet, use sets, if at all possible).
+* If data returned from the query is not what you expect, make sure you're generating the right graphql type.
+   * You can tell you're mocking the wrong one if the return values look something like `<mock-value-for-field-"formatted_amount">`
+
+
+:::note
+Make sure the component and the test use the same environment (i.e. there's no `<RelayEnvironmentProvider environment={RelayFBEnvironment}>` somewhere nested in your test React tree.
+:::
+
+
+## Epilogue
+
+Examples here use `testing-library-react`, but it works with the `react-test-renderer` as well.
+
+<FbInternalOnly>
+
+See [D23078476](https://www.internalfb.com/diff/D23078476).
+
+</FbInternalOnly>
+
+<DocsRating />

package/llm-docs/guides/throw-on-field-error-directive.mdx

@@ -0,0 +1,58 @@
+---
+id: throw-on-field-error-directive
+title: '@throwOnFieldError Directive'
+slug: /guides/throw-on-field-error-directive/
+description: Relay guide to @throwOnFieldError
+keywords:
+  - directive
+  - optional
+  - errors
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+:::tip
+Both `@catch` and `@throwOnFieldError` only handle field errors in the
+query/fragment/mutation in which they are used. They **do not** handle errors
+related to fields in any spread fragments.
+:::
+
+The `@throwOnFieldError` directive can be added to fragments and queries. When
+this directive is used, the Relay runtime will throw an exception if a field
+with a field error is encountered while reading the fragment or query, or if
+Relay is missing data due to a
+[graph relationship change](../debugging/why-null.mdx#graph-relationship-change).
+
+In addition to causing the Relay runtime to throw an exception if a field error
+is encountered, the `@throwOnFieldError` directive also enables generation of
+non-null Flow types for fields that have the `@semanticNonNull` directive in the
+schema. This means that if a field has the `@semanticNonNull` directive, the
+generated Flow type for that field will be non-nullable; if an error were to
+occur while reading that field, the thrown exception will prevent your
+application from receiving a null value. Making a previously-nullable field
+non-null may make many existing `@required` directives unnecessary; you can use
+the
+[remove-unnecessary-required-directives codemod](../guides/codemods.mdx#remove-unnecessary-required-directives)
+to clean these up.
+
+To use the `@throwOnFieldError` directive, add it to a fragment or query in your
+Relay code. For example:
+
+```
+fragment MyFragment on User @throwOnFieldError {
+  id
+  name
+}
+```
+
+In this example, the `@throwOnFieldError` directive is added to the MyFragment
+fragment. If any of the fields in this fragment (in this case, id and name) have
+a field error, the Relay runtime will throw an exception at the time the
+fragment is read.
+
+If you wish to handle a specific field error locally within your
+`@throwOnFieldError` fragment or query instead of having that error throw, you
+can catch the error with [@catch](./catch-directive.mdx).
+
+**Read more about Relay's experimental support for
+[Semantic Nullability](./semantic-nullability.mdx).**

package/llm-docs/guides/type-emission.mdx

@@ -0,0 +1,414 @@
+---
+id: type-emission
+title: Type Emission
+slug: /guides/type-emission/
+description: Relay guide to type emission
+keywords:
+- type emission
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+As part of its normal work, the [**Relay Compiler**](../compiler) will emit type information for your language of choice that helps you write type-safe application code. These types are included in the artifacts that `relay-compiler` generates to describe your operations and fragments.
+
+## Operation variables
+
+The shape of the variables object used for query, mutation, or subscription operations.
+
+In this example the emitted type-information would require the variables object to contain an `artistID` key with a non-null string.
+
+<Tabs
+  defaultValue={fbContent({internal: 'Flow', external: 'TypeScript'})}
+  values={[
+    {label: 'Flow', value: 'Flow'},
+    {label: 'TypeScript', value: 'TypeScript'},
+  ]}>
+  <TabItem value="Flow">
+
+```javascript
+/**
+ * export type ExampleQuery$variables = {
+ *   +artistID: string,
+ * }
+ * export type ExampleQuery$data = {
+ *   +artist: {
+ *     +name: ?string,
+ *   }
+ * }
+ * export type ExampleQuery = {
+ *   +variables: ExampleQuery$variables,
+ *   +response: ExampleQuery$data,
+ * }
+ */
+
+const data = useLazyLoadQuery(
+  graphql`
+    query ExampleQuery($artistID: ID!) {
+      artist(id: $artistID) {
+        name
+      }
+    }
+  `,
+  // variables are expected to be of type ExampleQuery$variables
+  {artistID: 'banksy'},
+);
+```
+
+  </TabItem>
+
+  <TabItem value="TypeScript">
+
+```javascript
+/**
+ * export type ExampleQuery$variables = {
+ *   readonly artistID: string
+ * }
+ * export type ExampleQuery$data = {
+ *   readonly artist?: {
+ *     readonly name?: string
+ *   }
+ * }
+ * export type ExampleQuery = {
+ *   readonly variables: ExampleQuery$variables
+ *   readonly response: ExampleQuery$data
+ * }
+ */
+const data = useLazyLoadQuery(
+  graphql`
+    query ExampleQuery($artistID: ID!) {
+      artist(id: $artistID) {
+        name
+      }
+    }
+  `,
+  // variables are expected to be of type ExampleQuery$variables
+  {artistID: 'banksy'},
+);
+```
+
+  </TabItem>
+</Tabs>
+
+## Operation and fragment data
+
+The shape of the data selected in a operation or fragment, following the [data-masking] rules. That is, excluding any data selected by fragment spreads.
+
+In this example the emitted type-information describes the response data which is returned by `useLazyLoadQuery` (or `usePreloadedQuery`).
+
+<Tabs
+  defaultValue={fbContent({internal: 'Flow', external: 'TypeScript'})}
+  values={[
+    {label: 'Flow', value: 'Flow'},
+    {label: 'TypeScript', value: 'TypeScript'},
+  ]}>
+  <TabItem value="Flow">
+
+```javascript
+/**
+ * export type ExampleQuery$variables = {
+ *   +artistID: string,
+ * }
+ * export type ExampleQuery$data = {
+ *   +artist: {
+ *     +name: ?string,
+ *   }
+ * }
+ * export type ExampleQuery = {
+ *   +variables: ExampleQuery$variables,
+ *   +response: ExampleQuery$data,
+ * }
+ */
+
+// data is of type ExampleQuery$data
+const data = useLazyLoadQuery(
+  graphql`
+    query ExampleQuery($artistID: ID!) {
+      artist(id: $artistID) {
+        name
+      }
+    }
+  `,
+  {artistID: 'banksy'},
+);
+
+return props.artist && <div>{props.artist.name} is great!</div>
+```
+
+  </TabItem>
+
+  <TabItem value="TypeScript">
+
+```javascript
+/**
+ * export type ExampleQuery$variables = {
+ *   readonly artistID: string
+ * }
+ * export type ExampleQuery$data = {
+ *   readonly artist?: {
+ *     readonly name?: string
+ *   }
+ * }
+ * export type ExampleQuery = {
+ *   readonly variables: ExampleQuery$variables
+ *   readonly response: ExampleQuery$data
+ * }
+ */
+
+// data is of type ExampleQuery$data
+const data = useLazyLoadQuery(
+  graphql`
+    query ExampleQuery($artistID: ID!) {
+      artist(id: $artistID) {
+        name
+      }
+    }
+  `,
+  {artistID: 'banksy'},
+);
+
+return props.artist && <div>{props.artist.name} is great!</div>
+```
+
+  </TabItem>
+</Tabs>
+
+
+Similarly, in this example the emitted type-information describes the type of the prop to match the type of the fragment reference `useFragment` expects to receive.
+
+<Tabs
+  defaultValue={fbContent({internal: 'Flow', external: 'TypeScript'})}
+  values={[
+    {label: 'Flow', value: 'Flow'},
+    {label: 'TypeScript', value: 'TypeScript'},
+  ]}>
+  <TabItem value="Flow">
+
+```javascript
+/**
+ * export type ExampleFragmentComponent_artist$data = {
+ *   +name: string
+ * }
+ *
+ * export type ExampleFragmentComponent_artist$key = { ... }
+ */
+
+import type { ExampleFragmentComponent_artist$key } from "__generated__/ExampleFragmentComponent_artist.graphql"
+
+type Props = {
+  artist: ExampleFragmentComponent_artist$key,
+};
+
+export default ExampleFragmentComponent(props) {
+  // data is of type ExampleFragmentComponent_artist$data
+  const data = useFragment(
+    graphql`
+      fragment ExampleFragmentComponent_artist on Artist {
+        biography
+      }
+    `,
+    props.artist,
+  );
+
+  return <div>About the artist: {props.artist.biography}</div>;
+}
+```
+
+  </TabItem>
+
+  <TabItem value="TypeScript">
+
+```javascript
+/**
+ * export type ExampleFragmentComponent_artist$data = {
+ *   readonly name: string
+ * }
+ *
+ * export type ExampleFragmentComponent_artist$key = { ... }
+ */
+
+import { ExampleFragmentComponent_artist$key } from "__generated__/ExampleFragmentComponent_artist.graphql"
+
+interface Props {
+  artist: ExampleFragmentComponent_artist$key,
+};
+
+export default ExampleFragmentComponent(props: Props) {
+  // data is of type ExampleFragmentComponent_artist$data
+  const data = useFragment(
+    graphql`
+      fragment ExampleFragmentComponent_artist on Artist {
+        biography
+      }
+    `,
+    props.artist,
+  );
+
+  return <div>About the artist: {props.artist.biography}</div>;
+}
+```
+
+  </TabItem>
+</Tabs>
+
+## Fragment references
+
+The opaque identifier described in [data-masking] that a child container expects to receive from its parent, which represents the child container’s fragment spread inside the parent’s fragment.
+
+<OssOnly>
+
+:::important
+Please read [this important caveat](#single-artifact-directory) about actually enabling type-safe fragment reference checking.
+:::
+
+</OssOnly>
+
+Consider a component that [composes](../../guided-tour/rendering/fragments/#composing-fragments) the above fragment component example. In this example, the emitted type-information of the child component receives a unique opaque identifier type, called a fragment reference, which the type-information emitted for the parent’s fragment references in the location where the child’s fragment is spread. Thus ensuring that the child’s fragment is spread into the parent’s fragment _and_ the correct fragment reference is passed to the child component at runtime.
+
+<Tabs
+  defaultValue={fbContent({internal: 'Flow', external: 'TypeScript'})}
+  values={[
+    {label: 'Flow', value: 'Flow'},
+    {label: 'TypeScript', value: 'TypeScript'},
+  ]}>
+  <TabItem value="Flow">
+
+```javascript
+import { ExampleFragmentComponent } from "./ExampleFragmentComponent"
+
+/**
+ * import type { ExampleFragmentComponent_artist$fragmentType } from "ExampleFragmentComponent_artist.graphql";
+ *
+ * export type ExampleQuery$data = {
+ *   +artist: ?{
+ *     +name: ?string,
+ *     +$fragmentSpreads: ExampleFragmentComponent_artist$fragmentType,
+ *   }
+ * };
+ * export type ExampleQuery$variables = {
+ *   +artistID: string,
+ * }
+ * export type ExampleQuery = {
+ *   +variables: ExampleQuery$variables,
+ *   +response: ExampleQuery$data,
+ * }
+ */
+
+// data is of type ExampleQuery$data
+const data = useLazyLoadQuery(
+  graphql`
+    query ExampleQuery($artistID: ID!) {
+      artist(id: $artistID) {
+        name
+        ...ExampleFragmentComponent_artist
+      }
+    }
+  `,
+  {artistID: 'banksy'},
+);
+
+// Here only `data.artist.name` is directly visible,
+// the marker prop $fragmentSpreads indicates that `data.artist`
+// can be used for the component expecting this fragment spread.
+return <ExampleFragmentComponent artist={data.artist} />;
+```
+
+  </TabItem>
+
+  <TabItem value="TypeScript">
+
+```javascript
+import { ExampleFragmentComponent } from "./ExampleFragmentComponent"
+
+/**
+ * import { ExampleFragmentComponent_artist$fragmentType } from "ExampleFragmentComponent_artist.graphql";
+ *
+ * export type ExampleQuery$data = {
+ *   readonly artist?: {
+ *     readonly name: ?string,
+ *     readonly " $fragmentSpreads": ExampleFragmentComponent_artist$fragmentType
+ *   }
+ * }
+ * export type ExampleQuery$variables = {
+ *   readonly artistID: string
+ * }
+ * export type ExampleQuery = {
+ *   readonly variables: ExampleQuery$variables
+ *   readonly response: ExampleQuery$data
+ * }
+ */
+
+// data is of type ExampleQuery$data
+const data = useLazyLoadQuery(
+  graphql`
+    query ExampleQuery($artistID: ID!) {
+      artist(id: $artistID) {
+        name
+        ...ExampleFragmentComponent_artist
+      }
+    }
+  `,
+  {artistID: 'banksy'},
+);
+
+// Here only `data.artist.name` is directly visible,
+// the marker prop $fragmentSpreads indicates that `data.artist`
+// can be used for the component expecting this fragment spread.
+return <ExampleFragmentComponent artist={data.artist} />;
+```
+
+  </TabItem>
+</Tabs>
+
+<OssOnly>
+
+## Single artifact directory
+
+An important caveat to note is that by default strict fragment reference type-information will _not_ be emitted, instead they will be typed as `any` and would allow you to pass in any data to the child component.
+
+To enable this feature, you will have to tell the compiler to store all the artifacts in a single directory, by specifying the `artifactDirectory` in the
+compiler configuration:
+
+```
+{
+  // package.json
+  "relay": {
+    "artifactDirectory": "./src/__generated__",
+    ...
+  },
+  ...
+}
+```
+
+…and additionally inform the babel plugin in your `.babelrc` config where to look for the artifacts:
+
+```json
+{
+  "plugins": [
+    ["relay", { "artifactDirectory": "./src/__generated__" }]
+  ]
+}
+```
+
+It is recommended to alias this directory in your module resolution configuration such that you don’t need to specify relative paths in your source files. This is what is also done in the above examples, where artifacts are imported from a `__generated__` alias, rather than relative paths like `../../../../__generated__`.
+
+### Background information
+
+The reason is that `relay-compiler` and its artifact emission is stateless. Meaning that it does not keep track of locations of original source files and where the compiler previously saved the accompanying artifact on disk. Thus, if the compiler were to emit artifacts that try to import fragment reference types from _other_ artifacts, the compiler would:
+
+-   first need to know where on disk that other artifact exists;
+-   and update imports when the other artifact changes location on disk.
+
+Facebook uses a module system called [Haste], in which all source files are considered in a flat namespace. This means that an import declaration does not need to specify the path to another module and thus there is no need for the compiler to ever consider the above issues. I.e. an import only needs to specify the basename of the module filename and Haste takes care of actually finding the right module at import time. Outside of Facebook, however, usage of the Haste module system is non-existent nor encouraged, thus the decision to not import fragment reference types but instead type them as `any`.
+
+At its simplest, we can consider Haste as a single directory that contains all module files, thus all module imports always being safe to import using relative sibling paths. This is what is achieved by the single artifact directory feature. Rather than co-locating artifacts with their source files, all artifacts are stored in a single directory, allowing the compiler to emit imports of fragment reference types.
+
+</OssOnly>
+
+[data-masking]: ../../principles-and-architecture/thinking-in-relay#data-masking
+
+[Haste]: https://twitter.com/dan_abramov/status/758655309212704768
+
+<DocsRating />

package/llm-docs/home.mdx

@@ -0,0 +1,32 @@
+---
+id: home
+title: Home
+slug: /
+description: Relay documentation landing page
+keywords:
+- relay
+- graphql
+- data
+- introduction
+- home
+---
+
+# Relay Docs
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+Relay is a powerful [GraphQL](https://graphql.org/) client for [React](https://react.dev/). It embodies years of learning to give you **outstanding performance by default** while keeping your code **scalable and maintainable**.
+
+Relay brings the composability of React components to data fetching. Each component declares its own data needs, and Relay combines them into efficient pre-loadable queries. Every aspect of its design is to make the natural way of writing components also the most performant.
+
+## Features
+
+* **Declarative**: Just declare what data each component needs and Relay will handle generating [optimal queries](https://relay.dev/blog/2023/10/24/how-relay-enables-optimal-data-fetching/) for each surface.
+* **Composable**: Components act like building bricks that can click into place anywhere in your app without needing to manually update queries.
+* **Pre-fetchable**: Relay's generated queries allow you to start fetching data for your surface before your code even downloads or runs.
+* **Built-in UI patterns**: Relay implements loading states, pagination, refetching, optimistic updates, rollbacks, and other common UI behaviors that are tricky to get right.
+* **Consistent state**: Relay maintains a normalized data store, so components that observe the same data stay in sync even if they reach it by different queries.
+* **Type safe**: Relay generates TypeScript types for each GraphQL snippet so that errors are caught statically, not at runtime.
+* **Streaming/deferred data**: Declaratively defer parts of your query and Relay will progressively re-render your UI as the data streams in.
+* **Developer experience**: Relay's [editor support](./editor-support.mdx) provides autocompletion and go-to-definition for your GraphQL schema.

package/llm-docs/principles-and-architecture/architecture-overview.mdx

@@ -0,0 +1,24 @@
+---
+id: architecture-overview
+title: Architecture Overview
+slug: /principles-and-architecture/architecture-overview/
+description: Relay architecture overview guide
+keywords:
+- architecture
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+This document, together with [Runtime Architecture](../runtime-architecture/) and [Compiler Architecture](../compiler-architecture/), describes the high-level architecture of Relay. The intended audience includes developers interested in contributing to Relay, developers hoping to utilize the building blocks of Relay to create higher-level APIs, and anyone interested in understanding more about Relay internals. For developers wanting to learn more about _using_ Relay to build products, the [Tutorial](../tutorial/intro.mdx) is the best resource.
+
+## Core Modules
+
+Relay is composed of three core parts:
+
+-   **Relay Compiler:** A GraphQL to GraphQL optimizing _compiler_, providing general utilities for transforming and optimizing queries as well as generating build artifacts. A novel feature of the compiler is that it facilitates experimentation with new GraphQL features - in the form of custom directives - by making it easy to translate code using these directives into standard, spec-compliant GraphQL.
+-   **Relay Runtime:** A full-featured, high-performance GraphQL _runtime_ that can be used to build higher-level client APIs. The runtime features a normalized object cache, optimized "write" and "read" operations, a generic abstraction for incrementally fetching field data (such as for pagination), garbage collection for removing unreferenced cache entries, optimistic mutations with arbitrary logic, support for building subscriptions and live queries, and more.
+-   **React/Relay:** A high-level _product API_ that integrates the Relay Runtime with React. This is the primary public interface to Relay for most product developers, featuring APIs to fetch the data for a query or define data dependencies for reusable components (e.g. `useFragment`).
+
+Note that these modules are _loosely coupled_. For example, the compiler emits representations of queries in a well-defined format that the runtime consumes, such that the compiler implementation can be swapped out if desired. React/Relay relies only on the well-documented public interface of the runtime, such that the actual implementation can be swapped out. We hope that this loose coupling will allow the community to explore new use-cases such as the development of specialized product APIs using the Relay runtime or integrations of the runtime with view libraries other than React.
+
+<DocsRating />