- Notifications
You must be signed in to change notification settings - Fork93
🚦 Check your GraphQL query strings against a schema.
apollographql/eslint-plugin-graphql
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
[2022-01-25] Note - Upcoming Deprecation Plans: We (Apollo) are working towards fully deprecating this repository. We suggest migrating to the community-supportedgraphql-eslint. We'll share detailed migration documentation when everything here is ready to be officially deprecated, but just a heads up in case you're planning on adopting anything here for a new project (which you still can of course if this project works for you - support for this project will be minimal however).
An ESLint plugin that checks tagged query strings inside JavaScript, or queries inside.graphql files, against a GraphQL schema.
npm install eslint-plugin-graphql
eslint-plugin-graphql has built-in settings for four GraphQL clients out of the box:
If you want to lint your GraphQL schema, rather than queries, check outcjoudrey/graphql-schema-linter.
You'll need to import yourintrospection 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.
graphql-cli provides aget-schema command (in conjunction with a.graphqlconfig file) that makes retrieving remote schemas very simple.
apollo-codegen also provides anintrospect-schema command that can get your remote schemas as well
All of the rules provided by this plugin have a few options in common. There are examples of how to use these with Apollo, Relay, Lokka, FraQL and literal files further down.
env: Import default settings for your GraphQL client. Supported values:'apollo','relay','lokka','fraql''literal'. Defaults to'apollo'. This is used for the slight parsing differences in the GraphQL syntax between Apollo, Relay, Lokka and FraQL as well as giving nice defaults to some other options.tagName: The name of the template literal tag that this plugin should look for when searching for GraphQL queries. It has different defaults depending on theenvoption:'relay':'Relay.QL''internal': Special automatic value- others:
'gql','graphql'
You also have to specify a schema. You can either do it usingone of these options:
schemaJson: Your schema as JSON.schemaJsonFilepath: The absolute path to your schema as a .json file. (Warning: this variant is incompatible witheslint --cache.)schemaString: Your schema in the Schema Language format as a string.
Alternatively, you can use a.graphqlconfig file instead of the above three options. If you do there's one more option to know about:
projectName: In case you specify multiple schemas in your.graphqlconfigfile, choose which one to use by providing the project name here as a string.
There's an example on how to use a.graphqlconfig file further down.
This plugin relies on GraphQL queries being prefixed with a special tag. In Relay and Apollo this is done often, but some other clients take query strings without a tag. In this case,fake-tag can be used to define an identity tag that doesn't do anything except for tell the linter this is a GraphQL query:
importgqlfrom"fake-tag";constQUERY_VIEWER_NAME=gql` query ViewerName { viewer { name } }`;
Fake tags won’t be necessaryonce/* GraphQL */ comment tags are supported.
This plugin also lints GraphQL literal files ending on.gql or.graphql.In order to do so setenv to'literal' in your.eslintrc.js and tell eslint to check these files as well.
eslint. --ext .js --ext .gql --ext .graphql// In a file called .eslintrc.jsmodule.exports={parser:"babel-eslint",rules:{"graphql/template-strings":['error',{// Import default settings for your GraphQL client. Supported values:// 'apollo', 'relay', 'lokka', 'fraql', 'literal'env:'apollo',// Import your schema JSON hereschemaJson:require('./schema.json'),// OR provide absolute path to your schema JSON (but not if using `eslint --cache`!)// 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']}
// In a file called .eslintrc.jsmodule.exports={parser:"babel-eslint",rules:{"graphql/template-strings":['error',{// Import default settings for your GraphQL client. Supported values:// 'apollo', 'relay', 'lokka', 'fraql', 'literal'env:'relay',// Import your schema JSON hereschemaJson:require('./schema.json'),// OR provide absolute path to your schema JSON (but not if using `eslint --cache`!)// 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']}
// In a file called .eslintrc.jsmodule.exports={parser:"babel-eslint",rules:{"graphql/template-strings":['error',{// Import default settings for your GraphQL client. Supported values:// 'apollo', 'relay', 'lokka', 'fraql', 'literal'env:'lokka',// Import your schema JSON hereschemaJson:require('./schema.json'),// OR provide absolute path to your schema JSON (but not if using `eslint --cache`!)// 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']}
// In a file called .eslintrc.jsmodule.exports={parser:"babel-eslint",rules:{"graphql/template-strings":['error',{// Import default settings for your GraphQL client. Supported values:// 'apollo', 'relay', 'lokka', 'fraql', 'literal'env:'fraql',// Import your schema JSON hereschemaJson: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']}
// In a file called .eslintrc.jsmodule.exports={parser:"babel-eslint",rules:{"graphql/template-strings":['error',{// Import default settings for your GraphQL client. Supported values:// 'apollo', 'relay', 'lokka', 'fraql', 'literal'env:'literal',// Import your schema JSON hereschemaJson:require('./schema.json'),// OR provide absolute path to your schema JSON (but not if using `eslint --cache`!)// schemaJsonFilepath: path.resolve(__dirname, './schema.json'),// OR provide the schema in the Schema Language format// schemaString: printSchema(schema),// tagName is set automatically}]},plugins:['graphql']}
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-relatedproperties (schemaJson,schemaJsonFilepath andschemaString) from rule config.
// In a file called .eslintrc.jsmodule.exports={parser:"babel-eslint",rules:{"graphql/template-strings":['error',{// Import default settings for your GraphQL client. Supported values:// 'apollo', 'relay', 'lokka', 'fraql', 'literal'env:'literal'// no need to specify schema here, it will be automatically determined using .graphqlconfig}]},plugins:['graphql']}
In case you use additional schemas, specifyprojectName from.graphqlconfig for eachtagName:
module.exports={parser:"babel-eslint",rules:{"graphql/template-strings":['error',{env:'apollo',tagName:'FirstGQL',projectName:'FirstGQLProject'},{env:'relay',tagName:'SecondGQL',projectName:'SecondGQLProject'}]},plugins:['graphql']}
GraphQL validation rules can be configured in the eslint rule configuration using thevalidators option. The default selection depends on theenv setting. If noenv is specified, all rules are enabled by default.
Thevalidators 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:
ExecutableDefinitionsFieldsOnCorrectTypeFragmentsOnCompositeTypesKnownArgumentNamesKnownDirectives(disabled by default inrelay)KnownFragmentNames(disabled by default in all envs)KnownTypeNamesLoneAnonymousOperationNoFragmentCyclesNoUndefinedVariables(disabled by default inrelay)NoUnusedFragments(disabled by default in all envs)NoUnusedVariablesOverlappingFieldsCanBeMergedPossibleFragmentSpreadsProvidedRequiredArguments(disabled by default inrelay)ScalarLeafs(disabled by default inrelay)SingleFieldSubscriptionsUniqueArgumentNamesUniqueDirectivesPerLocationUniqueFragmentNamesUniqueInputFieldNamesUniqueOperationNamesUniqueVariableNamesValuesOfCorrectTypeVariablesAreInputTypesVariablesDefaultValueAllowedVariablesInAllowedPosition
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 asgraphql/named-operations.
// In a file called .eslintrc.jsmodule.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']}
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 and present in the schemaschema { query { viewer { name uuid } }}query ViewerName { viewer { name uuid }}Pass
// 'uuid' usually required but not present in the schema hereschema { query { viewer { name } }}query ViewerName { viewer { name }}Fail
// 'uuid' required and present in the schemaschema { query { viewer { uuid name } }}query ViewerName { viewer { name }}The rule is defined asgraphql/required-fields and requires therequiredFields option.
// In a file called .eslintrc.jsmodule.exports={rules:{'graphql/required-fields':['error',{env:'apollo',schemaJsonFilepath:path.resolve(__dirname,'./schema.json'),requiredFields:['uuid'],},],},plugins:['graphql']}
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 asgraphql/capitalized-type-name.
// In a file called .eslintrc.jsmodule.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']}
The No Deprecated Fields rule validates that no deprecated fields are part of the query. This is useful to discover fields that have been marked as deprecated and shouldn't be used.
Fail
// 'id' requested and marked as deprecated in the schemaschema { query { viewer { id: Int @deprecated(reason: "Use the 'uuid' field instead") uuid: String } }}query ViewerName { viewer { id }}The rule is defined asgraphql/no-deprecated-fields.
// In a file called .eslintrc.jsmodule.exports={rules:{'graphql/no-deprecated-fields':['error',{env:'relay',schemaJson:require('./schema.json')},],},plugins:['graphql']}
About
🚦 Check your GraphQL query strings against a schema.
Resources
Code of conduct
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.