Getting Started

Configuration

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

import graphqlPlugin from '@graphql-eslint/eslint-plugin'
 
export default [
  // ... other config
  {
    files: ['**/*.graphql'],
    languageOptions: {
      parser: graphqlPlugin.parser
    },
    plugins: {
      '@graphql-eslint': graphqlPlugin
    },
    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.

Extend Plugin Functionality to GraphQL Definitions in Code Files¹

When defining GraphQL schemas or operations directly in code files¹, you need to add an override to ensure that this plugin’s functionality is applied to those definitions as well.

import graphqlPlugin from '@graphql-eslint/eslint-plugin';
 
export default [
+ {
+   files: ['**/*.js'],
+   processor: graphqlPlugin.processor
+ },
  {
    files: ['**/*.graphql'],
    languageOptions: {
      parser: graphqlPlugin.parser
    },
    plugins: {
      '@graphql-eslint': graphqlPlugin
    },
    rules: {
      '@graphql-eslint/known-type-names': 'error'
    }
  }
]

Extended Linting Rules with GraphQL Schema

Some linting rules require access to the entire GraphQL schema. For example, the no-unreachable-types rule checks that all types are reachable through root-level fields.

To enable these rules, you need to inform ESLint how to identify and load your complete schema.

The GraphQL ESLint plugin integrates seamlessly with GraphQL Config  which it uses to automatically load your schema. GraphQL Config supports multiple ways to specify your schema, including .json (introspection) file, .graphql files, a URL endpoint, or a raw string.

This integration uses graphql-tools under the hood to handle the schema loading.

Here’s an example of a basic graphql.config.js file:

export default {
  schema: './schema.graphql'
}

Alternatively, you can define the schema directly within your ESLint configuration by specifying languageOptions.parserOptions.graphQLConfig.schema.

import graphqlPlugin from '@graphql-eslint/eslint-plugin'
 
export default [
  // ... other config
  {
    files: ['**/*.graphql'],
    languageOptions: {
      parser: graphqlPlugin.parser,
+     parserOptions: {
+       graphQLConfig: {
+         schema: './schema.graphql'
+       }
+     }
    },
    plugins: {
      '@graphql-eslint': graphqlPlugin
    },
    rules: {
      '@graphql-eslint/no-unreachable-types': 'error'
    }
  }
]

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¹ and/or .graphql files:

export default {
  schema: './schema.graphql',
+ documents: './src/**/*.graphql'
}

or via programmatic usage:

import graphqlPlugin from '@graphql-eslint/eslint-plugin'
 
export default [
  // ... other config
  {
    files: ['**/*.graphql'],
    languageOptions: {
      parser: graphqlPlugin.parser,
      parserOptions: {
        graphQLConfig: {
          schema: './schema.graphql',
+         documents: './src/**/*.graphql'
        }
      }
    },
    plugins: {
      '@graphql-eslint': graphqlPlugin
    },
    rules: {
      '@graphql-eslint/unique-operation-name': 'error'
    }
  }
]