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:
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
Also, make sure you have
graphql
dependency in your project.
To get started, create an override configuration for your ESLint, while applying it to to .graphql
files (do that even if you are declaring your operations in code files):
{
"overrides": [
{
"files": ["*.graphql"],
"parser": "@graphql-eslint/eslint-plugin",
"plugins": ["@graphql-eslint"],
"rules": {
"eol-last": "off",
"prettier/prettier": "off"
...
}
}
]
}
If you are using code files to store your GraphQL schema or your GraphQL operations, you can extend the behaviour of ESLint and extract those, by adding an additional override
that does that extraction processes:
{
"overrides": [
{
"files": ["*.tsx", "*.ts", "*.jsx", "*.js"],
"processor": "@graphql-eslint/graphql"
},
{
"files": ["*.graphql"],
"parser": "@graphql-eslint/eslint-plugin",
"plugins": ["@graphql-eslint"],
"rules": {
"eol-last": "off",
"prettier/prettier": "off"
}
}
]
}
Note: Make sure to disable
eol-last
andprettier/prettier
- otherwise, you might get an error (see dimaMachina#88).
If you are using graphql-config
- you are good to go. This package integrates with it automatically, and will use it to load your schema!
Linting process can be enriched and extended with GraphQL type information, if you are able to provide your GraphQL schema.
The parser allow 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"],
"parserOptions": {
"schema": "./schema.graphql"
}
}
You can find a complete documentation of the
parserOptions
here
Some rules requires type information to operate, it's marked in the docs of each plugin!
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 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"],
"parserOptions": {
"operations": ["./src/**/*.graphql"],
"schema": "./schema.graphql"
}
}
By default, ESLint VSCode plugin will not lint files with extensions other then js, jsx, ts, 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"],
"eslint.options": {
"extentions": [".js", ".graphql"]
}
}
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, next-line
or (current) line
.
You can find a list of ESLint directives here.
You can find a complete list of all available rules here
This repo doesn't exports a "recommended" set of rules - feel free to recommend us!
If you wish to learn more about this project, how the parser works, how to add custom rules and more, please refer to the docs directory)
If you think a rule is missing, or can be modified, feel free to report issues, on open PRs. We always welcome contributions.