# eslint-plugin-relay

> ESLint plugin for Relay.

Latest version **2.1.0** (published 2026-08-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install eslint-plugin-relay
pnpm add eslint-plugin-relay
yarn add eslint-plugin-relay
bun add eslint-plugin-relay
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2026-08-10 |
| First published | 2017-05-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 65.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 104 |
| Maintainers | fb, relay-bot |

## Links

- npm: https://www.npmjs.com/package/eslint-plugin-relay
- Repository: https://github.com/relayjs/eslint-plugin-relay
- Homepage: https://github.com/relayjs/eslint-plugin-relay#readme
- Issues: https://github.com/relayjs/eslint-plugin-relay/issues
- npm.io page: https://npm.io/package/eslint-plugin-relay

## Dependencies (1)

- [graphql](https://npm.io/package/graphql.md) ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0

## Recent versions

- 2.1.0 (latest) — 2026-08-10
- 0.0.0-main-fc4bf5240704b4f05d8c84d5c84c6915ebd4bf17 (main) — 2026-08-10
- 0.0.0-main-22c2bc8211fd25f1928f026433ce3de638ef6c13 — 2026-06-29
- 0.0.0-main-5435300cb5e2457ada5d5167e6f2d635d75010ad — 2026-06-29
- 0.0.0-main-97780ad2ab5560e224f399fe0edd805de81bfaaa — 2026-06-29
- 2.0.0 — 2025-05-12
- 0.0.0-main-315500d93784b14153ba90ff49ae7776c514e47e — 2025-05-12
- 0.0.0-main-5c313c6c715ffd154f150206c9e975ec8ef2e8fb — 2025-04-23
- 0.0.0-main-e39d0e7f7bfc174041e83f84d14760ca88a2b158 — 2025-04-22
- 0.0.0-main-24fd162eee099e3f8145f26b3e7d82fa60952466 — 2024-08-27
- 0.0.0-main-f74143f31723425ccf83df61de3bb9cea20d8619 — 2023-11-27
- 1.8.3 — 2021-11-11
- 1.8.2 — 2021-02-05
- 1.8.1 — 2020-08-03
- 1.8.0 — 2020-07-22
- … 50 more at https://npm.io/package/eslint-plugin-relay/versions

## README

# eslint-plugin-relay [![Build Status](https://travis-ci.org/relayjs/eslint-plugin-relay.svg?branch=master)](https://travis-ci.org/relayjs/eslint-plugin-relay) [![npm version](https://badge.fury.io/js/eslint-plugin-relay.svg)](http://badge.fury.io/js/eslint-plugin-relay)

`eslint-plugin-relay` is a plugin for [ESLint](http://eslint.org/) to catch common problems in code using [Relay](https://facebook.github.io/relay/) early.

## Install

`npm i --save-dev eslint-plugin-relay`

## How To Use

eslint-plugin-relay comes with shared recommended and strict configs.

Example `eslint.config.js` (or `eslint.config.ts`):
```js
import relay from 'eslint-plugin-relay';

export default defineConfig(
  // Other eslint properties here
  {
    files: ['**/*.{js,mjs,cjs,jsx,ts,tsx}'],
    plugins: {relay},
    ...relay.configs.recommended
  }
);
```

Example .eslintrc.js (for legacy versions of ESLint):

```js
{
  "extends": [
    "plugin:relay/recommended"
  ]
}
```

Instead of using a shared config, you can enable just the rules you want:

```js
module.exports = {
  // Other eslint properties here
  rules: {
    'relay/graphql-syntax': 'error',
    'relay/graphql-naming': 'error',
    'relay/must-colocate-fragment-spreads': 'warn',
    'relay/no-future-added-value': 'warn',
    'relay/unused-fields': 'warn',
    'relay/function-required-argument': 'warn',
    'relay/hook-required-argument': 'warn'
  },
  plugins: ['relay']
};
```



### Rule Descriptions

Brief descriptions for each rule:

- `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/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/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/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.

## Contribute

We actively welcome pull requests, learn how to [contribute](./CONTRIBUTING.md).

## License

`eslint-plugin-relay` is [MIT licensed](./LICENSE).

---
_Source: https://npm.io/package/eslint-plugin-relay · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._