Usage

Installation

Install the plugin package with your favourite package manager.

npm i -D @graphql-eslint/eslint-plugin

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

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

bun add --dev @graphql-eslint/eslint-plugin

Configuration

Create a new configuration object  in your eslint.config.js file to apply this plugin to .graphql files and configure the rules you want to enforce.

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'
      // ... other GraphQL-ESLint rules
    }
  }
]

Lint GraphQL Definitions in Code Files ^(Optional)

If you’re defining GraphQL schemas or operations directly within code files¹, check out the usage with .js/.jsx files.

Providing GraphQL Schema ^(Optional)

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 result), .graphql files, a URL endpoint, or a raw string.

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

Example of providing GraphQL schema:

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

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'
    }
  }
]

Providing GraphQL Operations ^(Optional)

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:

Example of providing GraphQL operations:

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

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'
    }
  }
]