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 query strings inside JavaScript or queries inside .graphql files against a GraphQL schema.

npm install eslint-plugin-graphql

Has built-in settings for three GraphQL clients out of the box:

1. Apollo client
2. Relay
3. Lokka

Importing schema JSON

You'll need to import your introspection query result or the schema as a string in the Schema Language format. This can be done if you define your ESLint config in a JS file. Note: we're always looking for better ways to get the schema, so please open an issue with suggestions.

Identity template literal tag

This plugin relies on GraphQL queries being prefixed with a special tag. In Relay and Apollo, this is always done, but other clients often take query strings without a tag. In this case, you can 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.

GraphQL literal files

This plugin also lints GraphQL literal files ending on .gql or .graphql. In order to do so set env to 'literal' in your .eslintrc.js and tell eslint to check these files as well.

eslint . --ext .js --ext .gql --ext .graphql

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', 'literal'
      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'),

      // OR provide the schema in the Schema Language format
      // schemaString: printSchema(schema),

      // 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', 'literal'
      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'),

      // OR provide the schema in the Schema Language format
      // schemaString: printSchema(schema),

      // 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', 'literal'
      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'),

      // OR provide the schema in the Schema Language format
      // schemaString: printSchema(schema),

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

Example config for literal graphql files

// 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', 'literal'
      env: 'literal',

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

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

      // OR provide the schema in the Schema Language format
      // schemaString: printSchema(schema),

      // tagName is set automatically
    }]
  },
  plugins: [
    'graphql'
  ]
}

Additional Schemas or Tags

This plugin can be used to validate against multiple schemas by identifying them with different tags. This is useful for applications interacting with multiple GraphQL systems. Additional schemas can simply be appended to the options list:

module.exports = {
  parser: "babel-eslint",
  rules: {
    "graphql/template-strings": ['error', {
      env: 'apollo',
      tagName: 'FirstGQL',
      schemaJson: require('./schema-first.json')
    }, {
      env: 'relay',
      tagName: 'SecondGQL',
      schemaJson: require('./schema-second.json')
    }]
  },
  plugins: [
    'graphql'
  ]
}

Example config when using .graphqlconfig

If you have .graphqlconfig file in the root of your repo you can omit schema-related properties (schemaJson, schemaJsonFilepath and schemaString) from rule config.

// 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', 'literal'
      env: 'literal'
      // no need to specify schema here, it will be automatically determined using .graphqlconfig
    }]
  },
  plugins: [
    'graphql'
  ]
}

In case you use additional schemas, specify projectName from .graphqlconfig for each tagName:

module.exports = {
  parser: "babel-eslint",
  rules: {
    "graphql/template-strings": ['error', {
      env: 'apollo',
      tagName: 'FirstGQL',
      projectName: 'FirstGQLProject'
    }, {
      env: 'relay',
      tagName: 'SecondGQL',
      projectName: 'SecondGQLProject'
    }]
  },
  plugins: [
    'graphql'
  ]
}

Selecting Validation Rules

GraphQL validation rules can be configured in the eslint rule configuration using the validators option. The default selection depends on the env setting. If no env is specified, all rules are enabled by default.

The validators setting can be set either to a list of specific validator names or to the special value "all".

module.exports = {
  parser: "babel-eslint",
  rules: {
    "graphql/template-strings": ['error', {
      env: 'apollo',
      validators: 'all',
      tagName: 'FirstGQL',
      schemaJson: require('./schema-first.json')
    }, {
      validators: ['FieldsOnCorrectType'],
      tagName: 'SecondGQL',
      schemaJson: require('./schema-second.json')
    }]
  },
  plugins: [
    'graphql'
  ]
}

The full list of available validators is:

• ArgumentsOfCorrectType
• DefaultValuesOfCorrectType
• FieldsOnCorrectType
• FragmentsOnCompositeTypes
• KnownArgumentNames
• KnownDirectives (disabled by default in relay)
• KnownFragmentNames (disabled by default in all envs)
• KnownTypeNames
• LoneAnonymousOperation
• NoFragmentCycles
• NoUndefinedVariables (disabled by default in relay)
• NoUnusedFragments (disabled by default in all envs)
• NoUnusedVariables
• OverlappingFieldsCanBeMerged
• PossibleFragmentSpreads
• ProvidedNonNullArguments (disabled by default in relay)
• ScalarLeafs (disabled by default in relay)
• UniqueArgumentNames
• UniqueFragmentNames
• UniqueInputFieldNames
• UniqueOperationNames
• UniqueVariableNames
• VariablesAreInputTypes
• VariablesInAllowedPosition

Named Operations Validation Rule

The Named Operation rule validates that all operations are named. Naming operations is valuable for including in server-side logs and debugging.

Pass

query FetchUsername {
  viewer {
    name
  }
}

Fail

query {
  viewer {
    name
  }
}

The rule is defined as graphql/named-operations and requires a schema and optional tagName.

// In a file called .eslintrc.js
module.exports = {
  parser: "babel-eslint",
  rules: {
    "graphql/template-strings": ['error', {
      env: 'apollo',
      schemaJson: require('./schema.json'),
    }],
    "graphql/named-operations": ['warn', {
      schemaJson: require('./schema.json'),
    }],
  },
  plugins: [
    'graphql'
  ]
}

Required Fields Validation Rule

The Required Fields rule validates that any specified required field is part of the query, but only if that field is available in schema. This is useful to ensure that query results are cached properly in the client.

Pass

// 'uuid' required

schema {
  query {
    viewer {
      uuid
      name
    }
  }
}

query ViewerName {
  viewer {
    name
    uuid
  }
}

Pass

// 'uuid' required

schema {
  query {
    viewer {
      name
    }
  }
}

query ViewerName {
  viewer {
    name
  }
}

Fail

// 'uuid' required

schema {
  query {
    viewer {
      uuid
      name
    }
  }
}

query ViewerName {
  viewer {
    name
  }
}

The rule is defined as graphql/required-fields and requires a schema and requiredFields, with an optional tagName and env.

// In a file called .eslintrc.js
module.exports = {
  rules: {
    'graphql/required-fields': [
      'error',
      {
        env: 'apollo',
        schemaJsonFilepath: path.resolve(__dirname, './schema.json'),
        requiredFields: ['uuid'],
      },
    ],
  },
  plugins: [
    'graphql'
  ]
}

Capitalization of a first letter of a Type name

This rule enforces that first letter of types is capitalized

Pass

query {
  someUnion {
    ... on SomeType {
      someField
    }
  }
}

Fail

query {
  someUnion {
    ... on someType {
      someField
    }
  }
}

The rule is defined as graphql/capitalized-type-name and requires a schema;

// In a file called .eslintrc.js
module.exports = {
  parser: "babel-eslint",
  rules: {
    "graphql/template-strings": ['error', {
      env: 'apollo',
      schemaJson: require('./schema.json'),
    }],
    "graphql/capitalized-type-name": ['warn', {
      schemaJson: require('./schema.json'),
    }],
  },
  plugins: [
    'graphql'
  ]
}

Changelog

v1.3.0

• add support for .graphqlconfig Roman Hotsiy in #80
• add graphql/capitalized-type-name rule to warn on uncapitalized type names DianaSuvorova in #81