relay-runtime 20.1.0 → 21.0.0

package/llm-docs/getting-started/babel-plugin.mdx

@@ -0,0 +1,31 @@
+---
+id: babel-plugin
+title: Relay Babel Plugin
+slug: /getting-started/babel-plugin/
+description: Setting up Relay's Babel plugin
+keywords:
+- babel
+---
+# Babel Plugin
+
+Relay requires a [Babel plugin](https://www.npmjs.com/package/babel-plugin-relay) to convert GraphQL to compiler-generated runtime artifacts. Depending upon what framework/bundler you are using, there may be a framework-specific plugin you can use:
+
+- Vite: [vite-plugin-relay](https://github.com/oscartbeaumont/vite-plugin-relay)
+- Next.js: [Relay config option](https://nextjs.org/docs/architecture/nextjs-compiler#relay)
+- SWC: [@swc/plugin-relay](https://www.npmjs.com/package/@swc/plugin-relay)
+
+If not, you can install the Babel plugin manually:
+
+```sh
+yarn add --dev babel-plugin-relay graphql
+```
+
+Add `"relay"` to the list of plugins in your `.babelrc` file:
+
+```javascript
+{
+  "plugins": ["relay"]
+}
+```
+
+Please note that the `"relay"` plugin should run before other plugins or presets to ensure the `graphql` template literals are correctly transformed. See Babel's [documentation on this topic](https://babeljs.io/docs/plugins/#pluginpreset-ordering).

package/llm-docs/getting-started/compiler-config.mdx

@@ -0,0 +1,25 @@
+---
+id: compiler-config
+title: Compiler Configuration
+slug: /getting-started/compiler-config/
+description: Schema description of the Relay Compiler configuration
+keywords:
+- compiler
+- configuration
+- config
+hide_table_of_contents: false
+---
+import CompilerConfig from '@site/src/compiler-config/CompilerConfig';
+import schema from '@compilerConfigJsonSchema';
+
+## Compiler Config Options
+
+For information about where the Relay compiler looks for its config file, or a minimal config, see the [Relay Compiler](./compiler.mdx#Configuration) page.
+
+If you need more advanced options of the Relay Compiler Config, the exhaustive full schema can be found below. The shape of the Relay Compiler Config is given as `ConfigFile`. Note that while the shapes are documented in pseudo TypeScript, the compiler is parsing them in Rust so some subtle differences may exist.
+
+:::tip
+Install the [Relay VSCode extension](../editor-support.mdx) to get autocomplete, hover tips, and type checking for the options in your Relay config.
+:::
+
+<CompilerConfig schema={schema} definitions={schema.$defs} />

package/llm-docs/getting-started/compiler.mdx

@@ -0,0 +1,82 @@
+---
+id: compiler
+title: Relay Compiler
+slug: /guides/compiler/
+description: Relay guide to the compiler
+keywords:
+- compiler
+---
+
+Relay depends upon ahead-of-time compilation of GraphQL queries and fragments to generate artifacts that are used at runtime.
+
+The Relay compiler is a command line tool that reads GraphQL fragments, queries, and mutations in your JavaScript code and generates TypeScript/Flow types and additional JavaScript code that gets included in your code via [Relay's Babel Plugin](./babel-plugin.mdx).
+
+This guide explains configuring and using the Relay Compiler.
+
+## Configuration
+
+The Relay compiler will look for a Relay config in the following locations. It's up to you to decide which location works best for your project.
+
+* `relay.config.json` in your project root
+* `relay.config.(js/mjs/ts)` in your project root
+* A `"relay"` key in your `package.json`
+
+The Relay compiler config tells Relay things like where it can find your GraphQL schema and what language your code is written in. A minimal Relay compiler config looks like this:
+
+```json title="relay.config.json"
+{
+  "src": "./src",
+  "schema": "./schema.graphql",
+  "language": "typescript"
+}
+```
+
+:::tip
+Install the [Relay VSCode extension](../editor-support.mdx) to get autocomplete, hover tips, and type checking for the options in your relay config.
+:::
+
+The compiler config is very powerful, and includes many specialized configuration options. For a full enumeration of the available options see the [Compiler Configuration](./compiler-config.mdx) page.
+
+
+## Running the compiler
+
+It is generally recommended that you add a `scripts` entry to your `package.json` to make it easy to run the Relay compiler for your project.
+
+```json title="package.json"
+{
+  "scripts": {
+    // change-line
+    "relay": "relay-compiler"
+  }
+}
+```
+
+With this added you can run the Relay compiler like so:
+
+```sh
+npm run relay
+```
+
+### Watch mode
+
+If you have [watchman](https://facebook.github.io/watchman) installed you can pass `--watch` to the Relay compiler to have it continue running and automatically update generated files as you edit your product code:
+
+```sh
+npm run relay --watch
+```
+
+### Codemods
+
+The Relay compiler supports some built in codemods. Learn more in the [Codemods Guide](../guides/codemods.mdx).
+
+### Document comparison (Experimental)
+
+The Relay compiler can compare two GraphQL documents to determine if one is a subset of another. Learn more in the [Document Comparison Guide](../guides/document-comparison.mdx).
+
+### Help
+
+To learn about the other capabilities of the Relay compiler see its extensive `--help` output:
+
+```sh
+npm run relay --help
+```

package/llm-docs/getting-started/lint-rules.mdx

@@ -0,0 +1,87 @@
+---
+id: lint-rules
+title: Relay ESLint Plugin
+slug: /getting-started/lint-rules/
+description: ESLint Plugin Relay
+keywords:
+- eslint
+- lint
+---
+
+One of the unique features enabled by Relay is the ability to statically detect unused GraphQL fields. This can [categorically prevent](https://relay.dev/blog/2023/10/24/how-relay-enables-optimal-data-fetching/) the "append only query" problem that is a common dysfunction in many GraphQL clients.
+
+![Relay ESLint Plugin](../../static/img/docs/no-unused-fields.png)
+
+This validation, and other helpful checks, are enabled by Relay's ESLint plugin [`eslint-plugin-relay`](https://www.npmjs.com/package/eslint-plugin-relay). **The Relay ESLint plugin is a key part of the Relay developer experience**.
+
+## Installation
+
+Assuming you have [ESLint](https://eslint.org/) already installed, you can add the Relay ESLint plugin to your project by running:
+
+```sh
+npm install --save-dev eslint-plugin-relay
+```
+
+Then update your ESLint configuration to include the plugin:
+
+```js tile="eslint.config.js"
+import relay from 'eslint-plugin-relay';
+
+export default [
+  // ... other ESlint Config
+  {
+    plugins: { relay },
+    rules: relay.configs['ts-recommended'].rules,
+  },
+];
+```
+
+## Rule Descriptions
+
+The following validation rules are included in the Relay ESLint plugin:
+
+### `relay/unused-fields`
+Ensures that every GraphQL field referenced is used within the module that includes it. This helps enable Relay's [optimal data fetching](https://relay.dev/blog/2023/10/24/how-relay-enables-optimal-data-fetching/).
+
+### `relay/no-future-added-value`
+Ensures code does not try to explicitly handle the `"%future added value"` enum variant which Relay inserts as a placeholder to ensure you handle the possibility that new enum variants may be added by the server after your application has been deployed.
+
+### `relay/graphql-syntax`
+Ensures each `graphql` tagged template literal contains syntactically valid GraphQL. This is also validated by the Relay Compiler, but the ESLint plugin can often provide faster feedback.
+
+### `relay/graphql-naming`
+Ensures GraphQL fragments and queries follow Relay's naming conventions. This is also validated by the Relay Compiler, but the ESLint plugin can often provide faster feedback.
+
+### `relay/function-required-argument`
+Ensures that `readInlineData` is always passed an explicit argument even though that argument is allowed to be `undefined` at runtime.
+
+### `relay/hook-required-argument`
+Ensures that Relay hooks are always passed an explicit argument even though that argument is allowed to be `undefined` at runtime.
+
+### `relay/must-colocate-fragment-spreads`
+Ensures that when a fragment spread is added within a module, that module directly imports the module which defines that fragment. This prevents the anti-pattern when one component fetches a fragment that is not used by a direct child component.
+**Note**: This rule leans heavily on Meta's globally unique module names. It likely won't work well in other environments.
+
+## Suppressing rules within graphql tags
+
+The following rules support suppression within graphql tags:
+
+- `relay/unused-fields`
+- `relay/must-colocate-fragment-spreads`
+
+Supported rules can be suppressed by adding `# eslint-disable-next-line relay/name-of-rule` to the preceding line:
+
+```js
+graphql`
+  fragment foo on Page {
+    # eslint-disable-next-line relay/must-colocate-fragment-spreads
+    ...unused1
+  }
+`;
+```
+
+Note that only the `eslint-disable-next-line` form of suppression works. `eslint-disable-line` doesn't currently work until graphql-js provides support for [parsing Comment nodes](https://github.com/graphql/graphql-js/issues/2241) in their AST.
+
+## Contributing
+
+If you wish to contribute to the Relay ESLint plugin, you can find the code on GitHub at [relay/eslint-plugin-relay](https://github.com/relayjs/eslint-plugin-relay/).

package/llm-docs/getting-started/production.mdx

@@ -0,0 +1,30 @@
+---
+id: production
+title: Production Setup
+slug: /getting-started/production/
+description: Setting up Relay for production use
+keywords:
+- production
+---
+
+Getting the most out of Relay in production requires a few extra steps. This page covers a list of best practices for taking Relay to production.
+
+## Persisted Queries (Trusted Documents)
+
+One of GraphQL's key innovations is that it enables clients to define arbitrary queries. While this unlocks a lot of flexibility, it also opens the doors to abuse. Scrapers can use GraphQL to scrape data from your site, and malicious users can use GraphQL to send large requests to your server that cause a denial of service. To prevent this, we recommend using [Persisted Queries](../guides/persisted-queries.mdx) also know as [Trusted Documents](https://benjie.dev/graphql/trusted-documents).
+
+With Persisted Queries, the set of queries that the client can send is locked in at build time. This means that scrapers and malicious attackers are limited to sending only the queries used by the client, just like REST. It also has the added benefit that the client code only needs to include a single id for each query rather than the whole query text.
+
+<!-- TODO add Entry Points here once we have better docs -->
+
+## Relay Lint Rules
+
+A key principle of Relay is data colocation where each component defines its own data dependencies. It's critical to [How Relay Enables Optimal Data Fetching](https://relay.dev/blog/2023/10/24/how-relay-enables-optimal-data-fetching/). However, this is often unintuitive for developers who are used to fetching data in a single query. Relay's ESLint rules can help enforce this pattern by ensuring no component fetches fields which it does not itself use.
+
+We recommend using the [`eslint-plugin-relay`](https://github.com/relayjs/eslint-plugin-relay), especially the `relay/unused-fields` rule.
+
+Learn how to install them: [Relay ESLint Plugin](./lint-rules.mdx).
+
+## Running the Relay Compiler in CI
+
+We recommend committing Relay's generated artifacts to source control along with your application code. This ensures generated types are present without needing an additional build, and allows for inspection of generated artifacts in code review. To ensure the generated artifacts are always in sync with the source code, we recommend running the Relay compiler in CI and ensuring it does not change any generated files. A example bash script which checks for changes can be found [here](https://github.com/facebook/relay/blob/0414c9ad0744483e349e07defcb6d70a52cf8b3c/scripts/check-git-status.sh).

package/llm-docs/getting-started/quick-start.mdx

@@ -0,0 +1,213 @@
+---
+id: quick-start
+title: Quick Start
+slug: /getting-started/quick-start/
+description: Get up and running with Relay
+keywords:
+- quick
+---
+This quick start guide will start with a new React app using Vite and show you how to add Relay to it.
+
+:::tip
+If you'd prefer an automated approach, [`create-relay-app`](https://github.com/tobias-tengler/create-relay-app) by Tobias Tengler will walk you through adding Relay to an existing React app via a series of prompts: `npm create @tobiastengler/relay-app`
+:::
+
+We will be building a simple app which shows Star Wars movies fetched from the [example Star Wars GraphQL API](https://graphql.org/swapi-graphql/) hosted by graphql.org.
+
+## Scaffold a React App
+
+We’ll start with a [Vite](https://vite.dev/) React app using TypeScript.
+
+```bash
+npm create vite -- --template react-ts
+```
+
+You’ll be prompted for a project name. Type: `relay-example`
+
+## Install Dependencies
+
+```bash
+cd relay-example
+
+# Runtime dependencies
+npm install relay-runtime react-relay
+# Dev dependencies
+npm install --save-dev babel-plugin-relay graphql relay-compiler
+```
+
+:::tip
+If you're using an AI coding assistant, install the Relay best practices skill to make your agent a Relay expert:
+
+```bash
+npx skills install facebook/relay
+```
+:::
+
+## Configure Vite to use Relay
+
+Relay uses a [Babel plugin](./babel-plugin.mdx) to insert code generated by the Relay compiler into your bundle. We can enable the Relay Babel plugin we installed earlier by configuring the React Vite plugin.
+
+```tsx title="vite.config.ts"
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [
+    // change-line
+    react({ babel: { plugins: ["relay"] } })
+  ],
+})
+```
+
+See [Babel Plugin](./babel-plugin.mdx) for information about how to configure the Babel plugin for other build systems.
+
+## Configure the Relay Compiler
+
+Next we will download the GraphQL schema for the Star Wars GraphQL endpoint.
+
+```bash
+curl -O https://raw.githubusercontent.com/graphql/swapi-graphql/refs/heads/master/schema.graphql
+```
+
+And define our `relay.config.json` config file which tells the [Relay Compiler](./compiler.mdx) which schema file we want it to use and other details about our project.
+
+```json title="relay.config.json"
+{
+  "src": "./src",
+  "schema": "./schema.graphql",
+  "language": "typescript"
+}
+```
+
+See [Relay Compiler](./compiler.mdx) for more information about configuring and running the Relay compiler.
+
+## Configure your Relay Environment
+
+To allow components within our application to fetch GraphQL we configure a Relay Environment to fetch from our test endpoint and add it to React context.
+
+```tsx title="src/main.tsx"
+import { StrictMode, Suspense } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App.tsx";
+import { RelayEnvironmentProvider } from "react-relay";
+import { Environment, Network, FetchFunction } from "relay-runtime";
+
+const HTTP_ENDPOINT = "https://graphql.org/graphql/";
+
+const fetchGraphQL: FetchFunction = async (request, variables) => {
+  const resp = await fetch(HTTP_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query: request.text, variables }),
+  });
+  if (!resp.ok) {
+    throw new Error("Response failed.");
+  }
+  return await resp.json();
+};
+
+const environment = new Environment({
+  network: Network.create(fetchGraphQL),
+});
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <RelayEnvironmentProvider environment={environment}>
+      <Suspense fallback="Loading...">
+        <App />
+      </Suspense>
+    </RelayEnvironmentProvider>
+  </StrictMode>
+);
+```
+
+See [Relay Environment](../api-reference/relay-runtime/relay-environment.mdx) for an overview of the Relay Environment and how to configure it.
+
+:::tip
+`<RelayEnvironmentProvider>` exposes your Environment via [React context](https://react.dev/learn/passing-data-deeply-with-context), so it must wrap your entire application.
+:::
+
+## Define your first Relay component
+
+Finally we can start defining the data we want to fetch and build our UI. Our app will fetch a list of films and render each one using a `<Film>` component.
+
+```tsx title="src/App.tsx"
+import { AppQuery } from "./__generated__/AppQuery.graphql";
+import { graphql, useLazyLoadQuery } from "react-relay";
+import Film from "./Film";
+
+export default function App() {
+  const data = useLazyLoadQuery<AppQuery>(
+    graphql`
+      query AppQuery {
+        allFilms {
+          films {
+            id
+            ...Film_item
+          }
+        }
+      }
+    `,
+    {}
+  );
+
+  const films = data?.allFilms?.films?.filter((film) => film != null);
+
+  return (
+    <div>
+      <h1>Star Wars Films</h1>
+      {films?.map((film) => (
+        <Film key={film.id} film={film} />
+      ))}
+    </div>
+  );
+}
+```
+
+## Define your first fragment
+
+One of Relay's core principles is that each component should define its own data dependencies. So, we define our `<Film>` component using a [GraphQL Fragment](https://graphql.org/learn/queries/#fragments).
+
+```typescript title="src/Film.tsx"
+import { graphql, useFragment } from "react-relay";
+import type { Film_item$key } from "./__generated__/Film_item.graphql";
+
+export default function FilmListItem(props: { film: Film_item$key; }) {
+  const film = useFragment<Film_item$key>(
+    graphql`
+      fragment Film_item on Film {
+        title
+        director
+      }
+    `,
+    props.film
+  );
+
+  return (
+    <li>
+      <b>{film.title}</b>: directed by <i>{film.director}</i>
+    </li>
+  );
+}
+```
+
+## Compile and run your app
+
+All that’s left is to run the Relay compiler and start your app!
+
+The Relay compiler generates TypeScript types and combines your queries and fragments into optimized representations. You have to run the Relay compiler each time you modify your GraphQL queries or fragments.
+
+:::tip
+If you have [Watchman](https://facebook.github.io/watchman/) installed you can run `npx relay-compiler --watch` to have the compiler run in watch mode, but you'll need to run `echo "{}" > .watchmanconfig` to create a Watchman root.
+:::
+
+```bash
+npx relay-compiler
+npm run dev
+```
+
+You should now be able to open your app in a browser: [http://localhost:5173/](http://localhost:5173/)
+
+May the force be with you!