@graphql-eslint/eslint-plugin
This project integrates GraphQL and ESLint, for a better developer experience.
Last updated 3 years ago by dotansimha .
MIT · Repository · Bugs · Original npm · Tarball · package.json 
$ npm install @graphql-eslint/eslint-plugin
SYNC missed versions from official npm registry.

This project integrates GraphQL and ESLint, for a better developer experience.

npm version

Created and maintained by The Guild

Key Features

  • 🚀 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!

Getting Started

Installation

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.

Configuration

To get started, create an override configuration for your ESLint, while applying it 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": {
        ...
      }
    }
  ]
}

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": {
        ...
      }
    }
  ]
}

Extended linting rules with GraphQL Schema

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!

Extended linting rules with siblings operations

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"
  }
}

VSCode Integration

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"],
}

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).

Disabling Rules

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.

Available Rules

You can find a complete list of all available rules here

Available Configs

This plugin exports a recommended config that enforces good practices and an all config that makes use of all rules (except for deprecated ones).

Enable it in your .eslintrc file with the extends option.

These 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.

{
  "overrides": [
    {
      "files": ["*.js"],
      "processor": "@graphql-eslint/graphql",
      "rules": {
        // your rules for JavaScript files
      }
    },
    {
      "files": ["*.graphql"],
-     "parser": "@graphql-eslint/eslint-plugin",
-     "plugins": ["@graphql-eslint"],
+     "extends": "plugin:@graphql-eslint/recommended", // or plugin:@graphql-eslint/all
      "rules": {
        // your rules for GraphQL files
      }
    }
  ]
}

prettier rule

The original prettier rule has been removed because eslint-plugin-prettier supports .graphql files well actually.

All you need to do is like the following for now:

// .eslintrc.js
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 overrides setting if https://github.com/prettier/eslint-plugin-prettier/pull/415 will be merged and released.

Please help to vote up if you want to speed up the progress.

Further Reading

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)

Contributions

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.

Code of Conduct

Help us keep GraphQL ESLint open and inclusive. Please read and follow our Code of Conduct as adopted from Contributor Covenant

License

Released under the MIT license.

Current Tags

  • 4.0.0-alpha.6                                ...           alpha (a month ago)
  • 3.20.1                                ...           latest (a year ago)

477 Versions

Maintainers (2)
ivolodin
dotansimha
Downloads
Total 1
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 1
Dependencies (7)
Dev Dependencies (0)
None
Dependents (1)

© 2010 - cnpmjs.org x YWFE | Home | YWFE