This project integrates GraphQL and ESLint, for a better developer experience.
Created and maintained by The Guild
- π 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!
- Introducing GraphQL-ESLint! @
the-guild.dev
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.
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.
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.
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!
While implementing this tool, we had to find solutions for a better integration of the GraphQL ecosystem and ESLint core.
GraphQL 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"
}
}
By default, ESLint VSCode plugin will not lint files with extensions other than js
, jsx
, ts
and tsx
.
In order to enable it processing other extensions, add the following section in settings.json
or workspace configuration.
{
"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact", "graphql"]
}
Currently, you also need a GraphQL IDE extension for syntax highlighting installed (which may potentially have its own linting) - for example GraphQL (by GraphQL Foundation).
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.
You can find a complete list of all available rules here.
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 |
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.
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
toplugins
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"
}
]
}
eslint-plugin-prettier
supports .graphql
files. 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'
}
},
// the following is required for `eslint-plugin-prettier@<=3.4.0` temporarily
// after https://github.com/prettier/eslint-plugin-prettier/pull/415
// been merged and released, it can be deleted safely
{
files: ['*.js/*.graphql'],
rules: {
'prettier/prettier': 'off'
}
}
]
}
You can take examples/prettier
as example.
It could be better to remove the unnecessary *.js/*.graphql
override setting if prettier/eslint-plugin-prettier#415 will be merged and released.
Please help to vote up if you want to speed up the progress.
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:
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.
Help us keep GraphQL ESLint open and inclusive. Please read and follow our Code of Conduct as adopted from Contributor Covenant.
Released under the MIT license.