Linting Overview

GraphQL Analyzer includes a configurable linting engine with rules for common GraphQL best practices.

Quick setup

Add to your .graphqlrc.yml:

extensions:
  graphql-analyzer:
    lint: recommended

The recommended preset enables rules that are objectively beneficial without being opinionated about architecture choices.

The recommended preset

Rule	Severity	Description
noAnonymousOperations	error	Require named operations
noDeprecated	warn	Alert on deprecated field usage
noDuplicateFields	warn	Disallow duplicate fields in selection sets
noHashtagDescription	warn	Disallow # comments as type descriptions
noUnreachableTypes	warn	Detect types unreachable from root operations
redundantFields	warn	Detect fields duplicated by fragment spreads
requireDeprecationReason	warn	Require reason in @deprecated directives
uniqueEnumValueNames	warn	Detect duplicate enum values across enums
noUnusedFragments	warn	Detect unused fragment definitions
noUnusedFields	warn	Detect unused schema fields

Additional rules

These rules are available but not in the recommended preset — enable them based on your project’s needs:

Rule	Description
alphabetize	Enforce alphabetical ordering
descriptionStyle	Enforce block vs inline description style
inputName	Require configurable suffix on input types
loneExecutableDefinition	Require one operation or fragment per file
namingConvention	Enforce naming conventions
noOnePlaceFragments	Detect fragments used in only one place
noScalarResultTypeOnMutation	Require mutations to return object types
noTypenamePrefix	Disallow field names prefixed with type name
operationNameSuffix	Enforce operation name conventions
requireDescription	Require descriptions on type definitions
requireFieldOfTypeQueryInMutationResult	Require Query field in mutation results
selectionSetDepth	Limit selection set nesting depth
strictIdInTypes	Require ID field in object types
uniqueNames	Ensure operation/fragment names are unique
noUnusedVariables	Detect unused query variables
matchDocumentFilename	Document — Enforces that operation and fragment names match the filename
noRootType	Schema — Disallows certain root type definitions in the schema
relayArguments	Schema — Enforce Relay-compliant pagination arguments on connection fields
relayConnectionTypes	Schema — Enforces Relay connection type conventions on types ending in ‘Connection’
relayEdgeTypes	Schema — Enforces Relay-compliant edge type definitions
relayPageInfo	Schema — Enforces that the PageInfo type follows the Relay specification
requireDeprecationDate	Schema — Requires @deprecated directives to include a deletion date
requireImportFragment	Document — Requires fragment spreads to have a corresponding import comment
requireNullableFieldsWithOneof	Schema — Requires all fields in @oneOf input types to be nullable
requireNullableResultInRoot	Schema — Requires root type fields to return nullable types for error resilience
requireTypePatternWithOneof	Schema — Enforces that types with @oneOf directive contain both ‘ok’ and ‘error’ fields

See the Rules Catalog for details on each rule.

Running rules through ESLint

If your project already uses ESLint, you can run the same rules through the @graphql-analyzer/eslint-plugin — a drop-in replacement for @graphql-eslint/eslint-plugin. Configuration lives in the same .graphqlrc.yaml, so your editor, CI, and ESLint all see an identical ruleset.

Rule contexts

Rules run in different contexts depending on how much information they need:

Context	Scope	Speed	Where it runs
Standalone Document	Single document, no schema	Fast	LSP + CLI
Document-Schema	Single document + schema	Fast	LSP + CLI
Project-Wide	All documents + schema	Slow	CLI (by default)

Project-wide rules can be slow on large projects. If you experience latency in the editor, disable them in config and enable them in CI via graphql check --rule noUnusedFields=error.