ESLint Plugin GraphQL

4.0.0 verified Sat Apr 25 auth: no javascript

An ESLint plugin that validates GraphQL query strings in JavaScript tagged template literals and .graphql files against a GraphQL schema. Version 4.0.0 supports Node >=10.0 and peer dependency graphql ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0. Maintained under the Apollo GraphQL ecosystem. Provides built-in client profiles for Apollo, Relay, Lokka, and FraQL. Unlike graphql-schema-linter (which validates schema definitions), this plugin focuses on linting query usage in application code. Release cadence is irregular; latest release (4.0.0) was published in 2020.

Common errors

error Error: Cannot find module 'graphql' ↓

cause Missing peer dependency graphql.

fix

npm install graphql@^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 --save-dev

error Definition for rule 'graphql/template-strings' was not found ↓

cause Plugin not registered in ESLint config.

fix

Add plugins: ['graphql'] to your ESLint config (or equivalent for flat config).

error Invalid option 'schema' - must be one of schemaJson, schemaJsonFilepath, schemaString ↓

cause Using unknown option name 'schema' instead of correct one.

fix

Use schemaJson, schemaJsonFilepath, or schemaString.

error Cannot read property 'schema' of undefined ↓

cause Missing or malformed .graphqlconfig file or missing projectName.

fix

Ensure .graphqlconfig is correctly formatted and includes a default or specified project.

Warnings

gotcha The plugin only lints tagged template literals; untagged strings are ignored. ↓

fix Use a tag (e.g., gql from graphql-tag or fake-tag) before your query string.

deprecated ESLint <9 requires plugins to be added via 'plugins' array; flat config (>=9) is supported by this package but may require additional setup. ↓

fix For ESLint <9, use .eslintrc with plugins: ['graphql']. For ESLint >=9, use flat config as shown in quickstart.

gotcha schemaJsonFilepath option is incompatible with eslint --cache. ↓

fix Use schemaJson or schemaString instead of schemaJsonFilepath if caching is needed.

breaking v4.0.0 dropped support for Node <10 and older graphql versions. ↓

fix Ensure Node >=10 and graphql ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0.

gotcha Importing schema from a remote source using .graphqlconfig may not work if project name is missing. ↓

fix Set projectName option if your .graphqlconfig defines multiple projects.

Install

npm install eslint-plugin-graphql

yarn add eslint-plugin-graphql

pnpm add eslint-plugin-graphql

Imports

default

wrong

// Do not use:
import graphqlPlugin from 'eslint-plugin-graphql';
// Plugin is loaded via ESLint config, not directly imported.

correct

module.exports = {
  plugins: ['graphql'],
  rules: {
    'graphql/template-strings': ['error', { env: 'apollo', schemaJson: {} }]
  }
}

This is a CommonJS ESLint plugin; import it via ESLint config file, not in application code.

fake-tag

wrong

// Do not use an untagged template string:
const query = `{ __typename }`;
// The plugin only recognizes tagged strings.

correct

import gql from 'fake-tag';
const query = gql`{ __typename }`

Use fake-tag (or a real GraphQL client tag like gql from graphql-tag) to provide an identity tag for untagged queries.

template-strings

wrong

// Misspelling or wrong rule name:
'graphql/templateString': 'error'
// The correct rule name is 'template-strings'.

correct

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

The plugin registers a single rule 'template-strings'. Use it with an array of options including env and schema definition.

Quickstart

Flat ESLint config setup with Apollo client env, loading schema from JSON, and a sample tagged GraphQL query.

// eslint.config.js (ESLint >=9 flat config)
import graphqlPlugin from 'eslint-plugin-graphql';
import { readFileSync } from 'fs';

export default [
  {
    plugins: {
      graphql: graphqlPlugin
    },
    rules: {
      'graphql/template-strings': ['error', {
        env: 'apollo',
        schemaJson: JSON.parse(readFileSync('./schema.json', 'utf8'))
      }]
    }
  }
];

// In a .js file:
import gql from 'graphql-tag';
const query = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
    }
  }
`;