@@ -11,7 +11,7 @@ import PrettierIcon from '@icons/prettier.svg?svgr'
1111import StackIcon from ' @icons/stack.svg?svgr'
1212import SvelteIcon from ' @icons/svelte.svg?svgr'
1313import VueIcon from ' @icons/vue.svg?svgr'
14- import { Cards , Steps } from ' @theguild/components'
14+ import { Cards , Steps , Tabs } from ' @theguild/components'
1515import { createIndexPage , getPageMap , MDXRemote } from ' @theguild/components/server'
1616
1717# Usage
@@ -36,7 +36,12 @@ npm i -D @graphql-eslint/eslint-plugin
3636
3737Create a new
3838[ configuration object] ( https://eslint.org/docs/latest/use/configure/configuration-files#configuration-objects )
39- in your ` eslint.config.js ` file to setup ` @graphql-eslint ` plugin.
39+ in your ` eslint.config.js ` file to apply this plugin to ` .graphql ` files and configure
40+ [ the rules] ( /rules ) you want to enforce.
41+
42+ > [ !WARNING]
43+ >
44+ > This step is necessary even if you are declaring operations and/or schema in code files[ ^ 1 ] .
4045
4146``` js filename="eslint.config.js"
4247import graphqlPlugin from ' @graphql-eslint/eslint-plugin'
@@ -50,11 +55,140 @@ export default [
5055 },
5156 plugins: {
5257 ' @graphql-eslint' : graphqlPlugin
58+ },
59+ rules: {
60+ ' @graphql-eslint/known-type-names' : ' error'
61+ // ... other GraphQL-ESLint rules
62+ }
63+ }
64+ ]
65+ ```
66+
67+ ### Lint GraphQL Definitions in Code Files <sup >_ (Optional)_ </sup >
68+
69+ If you're defining GraphQL schemas or operations directly within code files[ ^ 1 ] , check out
70+ [ the usage with ` .js ` /` .jsx ` ] ( ./usage/js ) files.
71+
72+ ### Providing GraphQL Schema <sup >_ (Optional)_ </sup >
73+
74+ Some linting rules require access to the entire GraphQL schema. For example, the
75+ [ no-unreachable-types] ( ../rules/no-unreachable-types ) rule checks that all types are reachable
76+ through root-level fields.
77+
78+ To enable these rules, you need to inform ESLint how to identify and load your complete schema.
79+
80+ The GraphQL ESLint plugin integrates seamlessly with
81+ [ GraphQL Config] ( https://the-guild.dev/graphql/config ) which it uses to automatically load your
82+ schema. GraphQL Config supports multiple ways to specify your schema, including ` .json `
83+ (introspection) file, ` .graphql ` files, a URL endpoint, or a raw string.
84+
85+ > This integration uses [ ` graphql-tools ` ] ( https://the-guild.dev/graphql/tools ) under the hood to
86+ > handle the schema loading.
87+
88+ Example of providing GraphQL schema:
89+
90+ <Tabs items = { [' GraphQL Config' ' Programmatic Usage' } >
91+ <Tabs.Tab >
92+
93+ ``` js filename="graphql.config.js"
94+ export default {
95+ schema: ' ./schema.graphql'
96+ }
97+ ```
98+
99+ </Tabs.Tab >
100+
101+ <Tabs.Tab >
102+ Alternatively, you can provide the schema directly within your ESLint configuration by specifying
103+ ` languageOptions.parserOptions.graphQLConfig.schema ` .
104+
105+ ``` diff filename="eslint.config.js"
106+ import graphqlPlugin from '@graphql-eslint/eslint-plugin'
107+
108+ export default [
109+ // ... other config
110+ {
111+ files: ['**/*.graphql'],
112+ languageOptions: {
113+ parser: graphqlPlugin.parser,
114+ + parserOptions: {
115+ + graphQLConfig: {
116+ + schema: './schema.graphql'
117+ + }
118+ + }
119+ },
120+ plugins: {
121+ '@graphql-eslint': graphqlPlugin
122+ },
123+ rules: {
124+ '@graphql-eslint/no-unreachable-types': 'error'
125+ }
126+ }
127+ ]
128+ ```
129+
130+ </Tabs.Tab >
131+ </Tabs >
132+
133+ ### Providing GraphQL Operations <sup >_ (Optional)_ </sup >
134+
135+ While implementing this tool, we had to find solutions for a better integration of the GraphQL
136+ ecosystem and ESLint core.
137+
138+ GraphQL's operations can be distributed across many files, while ESLint operates on one file at a
139+ time. If you are using GraphQL fragments in separate files, some rules might yield incorrect
140+ results, due the missing information.
141+
142+ To workaround that, we allow you to provide additional information on your GraphQL operations,
143+ making it available for rules while doing the actual linting.
144+
145+ To provide that, we are using ` graphql-tools ` loaders to load your sibling operations and fragments,
146+ just specify a glob expression(s) that points to your code[ ^ 1 ] and/or ` .graphql ` files:
147+
148+ Example of providing GraphQL operations:
149+
150+ <Tabs items = { [' GraphQL Config' ' Programmatic Usage' } >
151+ <Tabs.Tab >
152+ ``` diff filename="graphql.config.js"
153+ export default {
154+ schema: './schema.graphql',
155+ + documents: './src/**/*.graphql'
156+ }
157+ ```
158+ </Tabs.Tab >
159+
160+ <Tabs.Tab >
161+ Alternatively, you can provide the documents directly within your ESLint configuration by specifying
162+ ` languageOptions.parserOptions.graphQLConfig.documents ` .
163+
164+ ``` diff filename="eslint.config.js"
165+ import graphqlPlugin from '@graphql-eslint/eslint-plugin'
166+
167+ export default [
168+ // ... other config
169+ {
170+ files: ['**/*.graphql'],
171+ languageOptions: {
172+ parser: graphqlPlugin.parser,
173+ parserOptions: {
174+ graphQLConfig: {
175+ schema: './schema.graphql',
176+ + documents: './src/**/*.graphql'
177+ }
178+ }
179+ },
180+ plugins: {
181+ '@graphql-eslint': graphqlPlugin
182+ },
183+ rules: {
184+ '@graphql-eslint/unique-operation-name': 'error'
53185 }
54186 }
55187]
56188```
57189
190+ </Tabs.Tab >
191+ </Tabs >
58192</Steps >
59193
60194## Usage
@@ -74,3 +208,5 @@ export default [
74208 PrettierIcon
75209 }}
76210/>
211+
212+ [ ^ 1 ] : Code files (e.g., ` .js ` , ` .jsx ` , ` .ts ` , ` .tsx ` files)
0 commit comments