![](\"./logo.png\"){kind=logo}
\n\n[](https://badge.fury.io/js/%40graphql-eslint%2Feslint-plugin)\n\n> Created and maintained by [The Guild](http://the-guild.dev)\n\n## Key Features\n\n- ???? Integrates with ESLint core (as a ESTree parser)\n- ???? Works on `.graphql` files, `gql` usages and `/* GraphQL */` magic comments\n- ???? Lints both GraphQL schema and GraphQL operations\n- ???? Extended type info for more advanced usages\n- ???? Supports ESLint directives (for example: `eslint-disable-next-line`)\n- ???? Easily extendable - supports custom rules based on GraphQL's AST and ESLint API\n- ???? Validates, lints, prettifies and checks for best practices across GraphQL schema and GraphQL operations\n- ???? Integrates with [`graphql-config`](https://graphql-config.com)\n- ???? Integrates and visualizes lint issues in popular IDEs (VSCode / WebStorm)\n\n> Special thanks to [ilyavolodin](https://github.com/ilyavolodin) for his work on a similar project!\n\n![](\"https://thumbs.gfycat.com/ActualTerrificDog-size_restricted.gif\")
\n\n## Getting Started\n\n- [Introducing GraphQL-ESLint!](https://the-guild.dev/blog/introducing-graphql-eslint) @ `the-guild.dev`\n\n### Installation\n\nStart by installing the plugin package, which includes everything you need:\n\n```sh\nyarn add -D @graphql-eslint/eslint-plugin\n```\n\nOr, with NPM:\n\n```sh\nnpm install --save-dev @graphql-eslint/eslint-plugin\n```\n\n> Make sure you have `graphql` dependency in your project.\n\n## Configuration\n\nTo get started, define an override in your ESLint config to apply this plugin to `.graphql` files. Add the [rules](docs/README.md) you want applied.\n\n> ???? Important! This step is necessary even if you are declaring operations and/or schema in code files.\n\n```json\n{\n \"overrides\": [\n {\n \"files\": [\"*.graphql\"],\n \"parser\": \"@graphql-eslint/eslint-plugin\",\n \"plugins\": [\"@graphql-eslint\"],\n \"rules\": {\n \"@graphql-eslint/known-type-names\": \"error\"\n }\n }\n ]\n}\n```\n\nIf 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](#using-a-remote-schema-or-rules-with-constraints-that-span-the-entire-schema).\n\n### Apply this plugin to GraphQL definitions defined in code files\n\nIf 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.\n\n```diff\n{\n \"overrides\": [\n+ {\n+ \"files\": [\"*.js\"],\n+ \"processor\": \"@graphql-eslint/graphql\"\n+ },\n {\n \"files\": [\"*.graphql\"],\n \"parser\": \"@graphql-eslint/eslint-plugin\",\n \"plugins\": [\"@graphql-eslint\"],\n \"rules\": {\n \"@graphql-eslint/known-type-names\": \"error\"\n }\n }\n ]\n}\n```\n\nUnder 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.\n\n### Extended linting rules with GraphQL Schema\n\nSome rules require an understanding of the entire schema at once. For example, [no-unreachable-types](https://github.com/dotansimha/graphql-eslint/blob/master/docs/rules/no-unreachable-types.md#no-unreachable-types) checks that all types are reachable by root-level fields.\n\nTo use these rules, you'll need to tell ESLint how to identify the entire set of schema definitions.\n\nIf you are using [`graphql-config`](https://graphql-config.com), you are good to go. `graphql-eslint` integrates with it automatically and will use it to load your schema!\n\nAlternatively, you can define `parserOptions.schema` in the `*.graphql` override in your ESLint config.\n\nThe 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:\n\n```diff\n{\n \"files\": [\"*.graphql\"],\n \"parser\": \"@graphql-eslint/eslint-plugin\",\n \"plugins\": [\"@graphql-eslint\"],\n \"rules\": {\n \"@graphql-eslint/no-unreachable-types\": \"error\"\n },\n+ \"parserOptions\": {\n+ \"schema\": \"./schema.graphql\"\n+ }\n}\n```\n\n> You can find a complete [documentation of the `parserOptions` here](docs/parser-options.md).\n\n> Some rules require type information to operate, it's marked in the docs for each rule!\n\n### Extended linting rules with siblings operations\n\nWhile implementing this tool, we had to find solutions for a better integration of the GraphQL ecosystem and ESLint core.\n\nGraphQL 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.\n\nTo workaround that, we allow you to provide additional information on your GraphQL operations, making it available for rules while doing the actual linting.\n\nTo 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:\n\n```diff\n{\n \"files\": [\"*.graphql\"],\n \"parser\": \"@graphql-eslint/eslint-plugin\",\n \"plugins\": [\"@graphql-eslint\"],\n \"rules\": {\n \"@graphql-eslint/unique-operation-name\": \"error\"\n },\n \"parserOptions\": {\n+ \"operations\": \"./src/**/*.graphql\",\n \"schema\": \"./schema.graphql\"\n }\n}\n```\n\n### VSCode Integration\n\nBy default, [ESLint VSCode plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) will not lint files with extensions other than `js`, `jsx`, `ts` and `tsx`.\n\nIn order to enable it processing other extensions, add the following section in `settings.json` or workspace configuration.\n\n```json\n{\n \"eslint.validate\": [\"javascript\", \"javascriptreact\", \"typescript\", \"typescriptreact\", \"graphql\"]\n}\n```\n\nCurrently, you also need a GraphQL IDE extension for syntax highlighting installed (which may potentially have its own linting) - for example [GraphQL (by GraphQL Foundation)](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql).\n\n### Disabling Rules\n\nThe `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.\n\nTo disable ESLint for a specific line, you can do:\n\n```graphql\n# eslint-disable-next-line\ntype Query {\n foo: String!\n}\n```\n\nYou can also specify specific rules to disable, apply it over the entire file, `eslint-disable-next-line` or current `eslint-disable-line`.\n\nYou can find a list of [ESLint directives here](https://eslint.org/docs/2.13.1/user-guide/configuring#disabling-rules-with-inline-comments).\n\n## Available Rules\n\nYou can find a complete list of [all available rules here](docs/README.md).\n\n### Deprecated Rules\n\nSee [docs/deprecated-rules.md](docs/deprecated-rules.md).\n\n## Available Configs\n\n\n|Name|Description|\n|:-:|-|\n|[`schema-recommended`](packages/plugin/src/configs/schema-recommended.ts)|enables recommended rules for schema (SDL) development|\n|[`schema-all`](packages/plugin/src/configs/schema-all.ts)|enables all rules for schema (SDL) development, except for those that require `parserOptions.operations` option|\n|[`operations-recommended`](packages/plugin/src/configs/operations-recommended.ts) |enables recommended rules for consuming GraphQL (operations) development|\n|[`operations-all`](packages/plugin/src/configs/operations-all.ts)|enables all rules for consuming GraphQL (operations) development|\n\n\n> If you are in a project that develops the GraphQL schema, you'll need `schema` rules. \n\n> If you are in a project that develops GraphQL operations (query/mutation/subscription), you'll need `operations` rules.\n\n> If you are in a monorepo project, you probably need both sets of rules.\n\n### Config usage\n\nFor example, to enable the `schema-recommended` config, enable it in your `.eslintrc` file with the `extends` option:\n\n> All configs under the hood set `parser` as `@graphql-eslint/eslint-plugin` and add `@graphql-eslint` to `plugins` array, so you don't need to specify them.\n\n```diff\n{\n \"overrides\": [\n {\n \"files\": [\"*.js\"],\n \"processor\": \"@graphql-eslint/graphql\"\n },\n {\n \"files\": [\"*.graphql\"],\n- \"parser\": \"@graphql-eslint/eslint-plugin\",\n- \"plugins\": [\"@graphql-eslint\"],\n+ \"extends\": \"plugin:@graphql-eslint/schema-recommended\"\n }\n ]\n}\n```\n\n### `prettier` rule\n\n`eslint-plugin-prettier` supports `.graphql` files. You need to do the following:\n\n```js\nmodule.exports = {\n overrides: [\n {\n files: ['*.js'],\n processor: '@graphql-eslint/graphql',\n extends: ['plugin:prettier/recommended']\n },\n {\n files: ['*.graphql'],\n parser: '@graphql-eslint/eslint-plugin',\n plugins: ['@graphql-eslint'],\n rules: {\n 'prettier/prettier': 'error'\n }\n },\n // the following is required for `eslint-plugin-prettier@<=3.4.0` temporarily\n // after https://github.com/prettier/eslint-plugin-prettier/pull/415\n // been merged and released, it can be deleted safely\n {\n files: ['*.js/*.graphql'],\n rules: {\n 'prettier/prettier': 'off'\n }\n }\n ]\n}\n```\n\nYou can take [`examples/prettier`](examples/prettier/.eslintrc.js) as example.\n\nIt could be better to remove the unnecessary `*.js/*.graphql` override setting if