ESLint
On this page

Usage

Usage — GraphQL ESLint documentation.

Quickstart

Installation

Install the plugin package with your favourite package manager.

npm i -D @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.

eslint.config.js
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 (e.g., .js, .jsx, .ts, .tsx 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.

Example of providing GraphQL schema:

graphql.config.js
export default {
  // a path to a local `.graphql` file
  schema: './schema.graphql',

  // a glob expression to load multiple files
  schema: './src/**/*.graphql',

  // paths to multiple `.graphql` files
  schema: ['./src/schema-a.graphql', './src/schema-b.graphql', './src/schema-c.graphql'],

  // a path to a local `.json` (introspection result) file
  schema: './schema.json',

  // a URL endpoint
  schema: 'https://my-server/graphql'
}
eslint.config.js
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.

The GraphQL ESLint plugin integrates seamlessly with GraphQL Config, which it uses to automatically load your sibling operations and fragments.

Example of providing GraphQL operations:

graphql.config.js
export default {
  // a path to a local `.graphql` file
  documents: './users.graphql',

  // a glob expression to load multiple files
  documents: './src/**/*.graphql',

  // paths to multiple `.graphql` files
  documents: ['./src/users.graphql', './src/posts.graphql', './src/user-fields.graphql']
}
eslint.config.js
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'
    }
  }
]

Usage

GraphQL Files

Usage with .graphql files

Code Files

Usage with code files .js/.jsx

Schema and Operations

Usage to lint both schema/operations

Multiple Projects

Usage to lint different schemas

Programmatic

Programmatic usage

Svelte

Usage with .svelte files

Vue

Usage with .vue files

Astro

Usage with .astro files

Prettier

Usage with eslint-plugin-prettier

Custom GraphQL Rules

Usage with custom GraphQL rules