Add docs page describing the Relay lint rules

Reviewed By: lynnshaoyu

Differential Revision:
D74739413

Privacy Context Container: L1125407

fbshipit-source-id: beafe4be0a8639109b8b8c6f595df7928f3e5334

Author: captbaritone

website/docs/getting-started/lint-rules.md

@@ -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 disfunction 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/).

website/docs/getting-started/production.md

@@ -23,6 +23,8 @@ A key principal of Relay is data colocation where each component defines its own
 
 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.md).
+
 ## 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).

website/docs/getting-started/quick-start.md

@@ -32,9 +32,9 @@ cd relay-example
 # Runtime dependencies
 npm install relay-runtime react-relay
 # Dev dependencies
-npm install --dev babel-plugin-relay graphql relay-compiler
+npm install --save-dev babel-plugin-relay graphql relay-compiler
 # Types
-npm install --dev @types/relay-runtime @types/react-relay
+npm install --save-dev @types/relay-runtime @types/react-relay
 ```
 
 ## Configure Vite to use Relay

website/sidebars.js

@@ -159,6 +159,7 @@ module.exports = {
         'getting-started/babel-plugin',
         'getting-started/compiler',
         'getting-started/compiler-config',
+        'getting-started/lint-rules',
         'editor-support',
         'getting-started/production',
       ],