Usage
Quickstart
Installation
Install the plugin package with your favourite package manager.
npm i -D @graphql-eslint/eslint-pluginMake sure you have graphql dependency in your project.
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 (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.
GraphQL Config uses GraphQL Tools and its loaders under
the hood to handle the schema loading. It also
supports multiple ways to specify your schema ,
including:
.json(introspection result).graphqlfiles- a URL endpoint
- or a raw string.
If you have a GraphQL Config configuration file in your project, the GraphQL-ESLint parser will automatically use it to load your GraphQL schema.
You should specify a schema key in the GraphQL Config configuration file to load your
GraphQL schema.
Alternatively, you can pass GraphQL Config options programmatically via
languageOptions.parserOptions.graphQLConfig in your eslint.config.js file.
Example of providing GraphQL schema:
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'
}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.
GraphQL Config uses GraphQL Tools and its loaders under
the hood to handle the loading of operations and fragments. It also
supports multiple ways to specify them .
If you have a GraphQL Config configuration file in your project, the GraphQL-ESLint parser will automatically use it to load your GraphQL operations.
You should specify a documents key in the GraphQL Config configuration file to load your
GraphQL operations.
Alternatively, you can pass GraphQL Config options programmatically via
languageOptions.parserOptions.graphQLConfig in your eslint.config.js file.
Example of providing GraphQL operations:
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']
}