@graphql-eslint/eslint-plugin

What is @graphql-eslint/eslint-plugin?

@graphql-eslint/eslint-plugin is an ESLint plugin that provides linting rules for GraphQL schema and operations. It helps developers enforce best practices, catch errors early, and maintain consistency in their GraphQL code.

What are @graphql-eslint/eslint-plugin's main functionalities?

Linting GraphQL Schema

This feature allows you to lint your GraphQL schema files. The example configuration enforces rules to ensure that all type names are known and warns about deprecated fields.

module.exports = {
  'plugins': ['@graphql-eslint'],
  'overrides': [
    {
      'files': ['*.graphql'],
      'parser': '@graphql-eslint/eslint-plugin',
      'rules': {
        '@graphql-eslint/known-type-names': 'error',
        '@graphql-eslint/no-deprecated': 'warn'
      }
    }
  ]
};

Linting GraphQL Operations

This feature allows you to lint GraphQL operations within your JavaScript files. The example configuration enforces rules to ensure that there are no unused fields and that the 'id' field is used when available.

module.exports = {
  'plugins': ['@graphql-eslint'],
  'overrides': [
    {
      'files': ['*.js'],
      'processor': '@graphql-eslint/graphql',
      'rules': {
        '@graphql-eslint/no-unused-fields': 'error',
        '@graphql-eslint/require-id-when-available': 'warn'
      }
    }
  ]
};

Custom Rules

This feature allows you to define custom linting rules for your GraphQL code. The example configuration shows how to set up a custom rule with specific options.

module.exports = {
  'plugins': ['@graphql-eslint'],
  'rules': {
    '@graphql-eslint/custom-rule': [
      'error',
      {
        'ruleOption': 'value'
      }
    ]
  }
};

Other packages similar to @graphql-eslint/eslint-plugin

eslint-plugin-graphql

eslint-plugin-graphql is another ESLint plugin that provides GraphQL linting capabilities. It focuses on validating GraphQL queries and schema definitions within JavaScript files. Compared to @graphql-eslint/eslint-plugin, it has fewer built-in rules and less flexibility for custom rules.

graphql-schema-linter

graphql-schema-linter is a standalone tool for linting GraphQL schemas. It provides a set of rules to enforce best practices and catch common errors in schema definitions. Unlike @graphql-eslint/eslint-plugin, it does not integrate directly with ESLint and is used as a separate command-line tool.

graphql-eslint

graphql-eslint is a package that provides a set of ESLint rules for GraphQL. It is similar to @graphql-eslint/eslint-plugin but focuses more on providing a comprehensive set of rules for both schema and operations. It also offers better integration with various GraphQL tools and libraries.

README

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

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

• Introducing GraphQL-ESLint! @ the-guild.dev

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

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"],
  "eslint.options": {
    "extentions": [".js", ".graphql"]
  }
}

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 plugins here

This repo doesn't exports a "recommended" set of rules - feel free to recommend us!

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)

Contributing

If you think a rule is missing, or can be modified, feel free to report issues, on open PRs. We always welcome contributions.