graphql-eslint

This project integrates GraphQL and ESLint, for a better developer experience.

Created and maintained by The Guild

Key Features

• 🚀 Integrates with ESLint core (as a ESTree parser)
• 🚀 Works on .graphql files, gql usages and /* GraphQL */ magic comments
• 🚀 Lints both GraphQL schema and GraphQL operations
• 🚀 Extended type info for more advanced usages
• 🚀 Supports ESLint directives (for example: eslint-disable-next-line)
• 🚀 Easily extendable – supports custom rules based on GraphQL’s AST and ESLint API
• 🚀 Validates, lints, prettifies and checks for best practices across GraphQL schema and GraphQL
  operations
• 🚀 Integrates with graphql-config
• 🚀 Integrates and visualizes lint issues in popular IDEs (VSCode / WebStorm)

Special thanks to ilyavolodin for his work on a similar project!

Getting Started

• Introducing GraphQL-ESLint! @
  the-guild.dev

Installation

Start by installing the plugin package, which includes everything you need:

yarn add -D @graphql-eslint/eslint-plugin

Or, with NPM:

npm install --save-dev @graphql-eslint/eslint-plugin

Make sure you have graphql dependency in your project.

Configuration

To get started, define an override in your ESLint config to apply this plugin to .graphql files.
Add the rules you want applied.

🚨 Important! This step is necessary even if you are declaring operations and/or schema in code
files.

{
  "overrides": [
    {
      "files": ["*.graphql"],
      "parser": "@graphql-eslint/eslint-plugin",
      "plugins": ["@graphql-eslint"],
      "rules": {
        "@graphql-eslint/known-type-names": "error"
      }
    }
  ]
}

If your GraphQL definitions are defined only in .graphql files, and you’re only using rules that
apply to individual files, you should be good to go 👍. If you would like use a remote schema or use
rules that apply across the entire collection of definitions at once, see
here.

Apply this plugin to GraphQL definitions defined in code files

If you are defining GraphQL schema or GraphQL operations in code files, you’ll want to define an
additional override to extend the functionality of this plugin to the schema and operations in those
files.

{
  "overrides": [
+   {
+     "files": ["*.js"],
+     "processor": "@graphql-eslint/graphql"
+   },
    {
      "files": ["*.graphql"],
      "parser": "@graphql-eslint/eslint-plugin",
      "plugins": ["@graphql-eslint"],
      "rules": {
        "@graphql-eslint/known-type-names": "error"
      }
    }
  ]
}

Under the hood, specifying the @graphql-eslint/graphql processor for code files will cause
graphql-eslint/graphql to extract the schema and operation definitions from these files into
virtual GraphQL documents with .graphql extensions. This will allow the overrides you’ve defined
for .graphql files, via "files": ["*.graphql"], to get applied to the definitions defined in
your code files.

Extended linting rules with GraphQL Schema

Some rules require an understanding of the entire schema at once. For example,
no-unreachable-types
checks that all types are reachable by root-level fields.
To use these rules, you’ll need to tell ESLint how to identify the entire set of schema definitions.
If you are using graphql-config, you are good to go.
graphql-eslint integrates with it automatically and will use it to load your schema!
Alternatively, you can define parserOptions.schema in the *.graphql override in your ESLint
config.
The parser allows you to specify a json file / graphql files(s) / url / raw string to locate your
schema (We are using graphql-tools to do that). Just add parserOptions.schema to your
configuration file:

{
  "files": ["*.graphql"],
  "parser": "@graphql-eslint/eslint-plugin",
  "plugins": ["@graphql-eslint"],
  "rules": {
    "@graphql-eslint/no-unreachable-types": "error"
  },
+ "parserOptions": {
+   "schema": "./schema.graphql"
+ }
}

You can find a complete documentation of the parserOptions here.

Some rules require type information to operate, it’s marked in the docs for each rule!

Extended linting rules with siblings operations

While implementing this tool, we had to find solutions for a better integration of the GraphQL
ecosystem and ESLint core.
GraphQL’s operations can be distributed across many files, while ESLint operates on one file at a
time. If you are using GraphQL fragments in separate files, some rules might yield incorrect
results, due the missing information.
To workaround that, we allow you to provide additional information on your GraphQL operations,
making it available for rules while doing the actual linting.
To provide that, we are using graphql-tools loaders to load your sibling operations and fragments,
just specify a glob expression(s) that points to your code/.graphql files:

{
  "files": ["*.graphql"],
  "parser": "@graphql-eslint/eslint-plugin",
  "plugins": ["@graphql-eslint"],
  "rules": {
    "@graphql-eslint/unique-operation-name": "error"
  },
  "parserOptions": {
+   "operations": "./src/**/*.graphql",
    "schema": "./schema.graphql"
  }
}

VSCode Integration

Use
ESLint VSCode extension
to integrate ESLint into VSCode.
For syntax highlighting you need a GraphQL extension (which may potentially have its own linting),
for example
GraphQL (by GraphQL Foundation).

Disabling Rules

The graphql-eslint parser looks for GraphQL comments syntax (marked with #) and will send it to
ESLint as directives. That means, you can use ESLint directives syntax to hint ESLint, just like in
any other type of files.
To disable ESLint for a specific line, you can do:

# eslint-disable-next-line
type Query {
  foo: String!
}

You can also specify specific rules to disable, apply it over the entire file,
eslint-disable-next-line or current eslint-disable-line.
You can find a list of
ESLint directives here.

Available Rules

You can find a complete list of all available rules here.

Deprecated Rules

See docs/deprecated-rules.md.

Available Configs

Name
Description

schema-recommended
enables recommended rules for schema (SDL) development

schema-all
enables all rules for schema (SDL) development, except for those that require parserOptions.operations option

operations-recommended
enables recommended rules for consuming GraphQL (operations) development

operations-all
enables all rules for consuming GraphQL (operations) development

relay
enables rules from Relay specification for schema (SDL) development

If you are in a project that develops the GraphQL schema, you’ll need schema rules.

If you are in a project that develops GraphQL operations (query/mutation/subscription), you’ll
need operations rules.

If you are in a monorepo project, you probably need both sets of rules, see
example of configuration.

Config usage

For example, to enable the schema-recommended config, enable it in your .eslintrc file with the
extends option:

All configs under the hood set parser as @graphql-eslint/eslint-plugin and add
@graphql-eslint to plugins array, so you don’t need to specify them.

{
  "overrides": [
    {
      "files": ["*.js"],
      "processor": "@graphql-eslint/graphql"
    },
    {
      "files": ["*.graphql"],
-     "parser": "@graphql-eslint/eslint-plugin",
-     "plugins": ["@graphql-eslint"],
+     "extends": "plugin:@graphql-eslint/schema-recommended"
    }
  ]
}

prettier rule

eslint-plugin-prettier supports .graphql files, and v4.1.0 supports graphql blocks even
better. You need to do the following:

module.exports = {
  overrides: [
    {
      files: ['*.js'],
      processor: '@graphql-eslint/graphql',
      extends: ['plugin:prettier/recommended']
    },
    {
      files: ['*.graphql'],
      parser: '@graphql-eslint/eslint-plugin',
      plugins: ['@graphql-eslint'],
      rules: {
        'prettier/prettier': 'error'
      }
    }
  ]
}

You can take examples/prettier as example.

Further Reading

If you wish to learn more about this project, how the parser works, how to add custom rules and more
please refer to the below links:

• Writing Custom Rules
• How the parser works?
• parserOptions

Contributions

Contributions, issues and feature requests are very welcome. If you are using this package and fixed
a bug for yourself, please consider submitting a PR!
And if this is your first time contributing to this project, please do read our
Contributor Workflow Guide
before you get started off.

Code of Conduct

Help us keep GraphQL ESLint open and inclusive. Please read and follow our
Code of Conduct as adopted
from Contributor Covenant.

License

Released under the MIT license.