eslint-plugin-graphql

What is eslint-plugin-graphql?

eslint-plugin-graphql is an ESLint plugin that provides GraphQL linting rules for your JavaScript and TypeScript projects. It helps ensure that your GraphQL queries, mutations, and subscriptions are syntactically correct and follow best practices.

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

Linting GraphQL Queries

This feature allows you to lint GraphQL queries within template strings. The configuration specifies the environment as 'literal' and uses a local schema file to validate the queries.

{
  "rules": {
    "graphql/template-strings": [
      "error",
      {
        "env": "literal",
        "schemaJson": require('./schema.json')
      }
    ]
  }
}

Linting GraphQL Files

This feature allows you to lint GraphQL operations in .graphql files. The configuration uses a local schema file to validate the operations and ensures that all operations are named.

{
  "rules": {
    "graphql/named-operations": [
      "error",
      {
        "schemaJson": require('./schema.json')
      }
    ]
  }
}

Custom Validation Rules

This feature allows you to enforce custom validation rules on your GraphQL queries. The example configuration ensures that every query includes the 'id' and '__typename' fields.

{
  "rules": {
    "graphql/required-fields": [
      "error",
      {
        "env": "apollo",
        "schemaJson": require('./schema.json'),
        "requiredFields": ["id", "__typename"]
      }
    ]
  }
}

Other packages similar to eslint-plugin-graphql

graphql-eslint

graphql-eslint is another ESLint plugin that provides a comprehensive set of rules for linting GraphQL schema and operations. It offers more granular control over linting rules and supports both GraphQL schema and operations in various file types. Compared to eslint-plugin-graphql, graphql-eslint provides a more extensive set of rules and better integration with GraphQL tools like Apollo and Relay.

README

eslint-plugin-graphql

An ESLint plugin that checks tagged template strings against a GraphQL schema.

npm install eslint-plugin-graphql

Supports three GraphQL clients out of the box:

1. Apollo client
2. Relay
3. Lokka

Coming soon: You can use it now with the manual approach described below, but we are working on easier tooling so you can just pass a GraphQL server URL.

Importing schema JSON

You'll need to import your introspection query result. This can be done if you define your ESLint config in a JS file.

Identity template literal tag

This plugin relies on GraphQL queries being prefixed with a special tag. In Relay, this is always done, but other clients like just take normal template literals without a tag. In this case, define an identity tag that doesn't do anything except for tell the linter this is a GraphQL query:

global.gql = (literals, ...substitutions) => {
    let result = "";

    // run the loop only for the substitution count
    for (let i = 0; i < substitutions.length; i++) {
        result += literals[i];
        result += substitutions[i];
    }

    // add the last literal
    result += literals[literals.length - 1];

    return result;
}

Code snippet taken from: https://leanpub.com/understandinges6/read#leanpub-auto-multiline-strings

Note: the linter rule could be extended to identify calls to various specific APIs to eliminate the need for a template literal tag, but this might just make the implementation a lot more complex for little benefit.

Example config for Apollo

// In a file called .eslintrc.js
module.exports = {
  "parser": "babel-eslint",
  "rules": {
    "graphql/template-strings": ['error', {
      // Import default settings for your GraphQL client. Supported values:
      // 'apollo', 'relay', 'lokka'
      env: 'apollo',

      // Import your schema JSON here
      schemaJson: require('./schema.json'),

      // OR provide absolute path to your schema JSON
      // schemaJsonFilepath: path.resolve(__dirname, './schema.json'),

      // tagName is gql by default
    }]
  },
  plugins: [
    'graphql'
  ]
}

Example config for Relay

// In a file called .eslintrc.js
module.exports = {
  "parser": "babel-eslint",
  "rules": {
    "graphql/template-strings": ['error', {
      // Import default settings for your GraphQL client. Supported values:
      // 'apollo', 'relay', 'lokka'
      env: 'relay',

      // Import your schema JSON here
      schemaJson: require('./schema.json'),

      // OR provide absolute path to your schema JSON
      // schemaJsonFilepath: path.resolve(__dirname, './schema.json'),

      // tagName is set for you to Relay.QL
    }]
  },
  plugins: [
    'graphql'
  ]
}

Example config for Lokka

// In a file called .eslintrc.js
module.exports = {
  "parser": "babel-eslint",
  "rules": {
    "graphql/template-strings": ['error', {
      // Import default settings for your GraphQL client. Supported values:
      // 'apollo', 'relay', 'lokka'
      env: 'lokka',

      // Import your schema JSON here
      schemaJson: require('./schema.json'),

      // OR provide absolute path to your schema JSON
      // schemaJsonFilepath: path.resolve(__dirname, './schema.json'),

      // Optional, the name of the template tag, defaults to 'gql'
      tagName: 'gql'
    }]
  },
  plugins: [
    'graphql'
  ]
}