documents
field#
The documents
field should point to your GraphQL documents: query
, mutation
, subscription
, and fragment
.
documents
is only required if you use plugins that generate code for the client-side.
You can specify either a string
pointing to your documents or string[]
pointing to multiple documents.
How to use it?#
Root-level#
You can specify the documents
field in your root level config:
schema: http://localhost:3000/graphql
documents: 'src/**/*.graphql'
generates:
./src/types.ts:
plugins:
- typescript
- typescript-operations
Output-file level#
You can also specify the documents
field in your generated file level config:
schema: http://server1.com/graphql
generates:
./src/types1.ts:
documents: 'src/**/*.graphql'
plugins:
- typescript
- typescript-operations
Document Scanner#
GraphQL Code Generator has a built-in document scanner, which means you can specify a .graphql
file or code files containing GraphQL documents (ex: .tsx
).
You can tell it to find documents in TypeScript files:
schema: http://server1.com/graphql
documents: 'src/**/!(*.d).{ts,tsx}'
Available Formats#
The following can be specified as a single value or as an array with mixed values.
-
Local File#
You can specify a string
to point to a single file:
documents: my-query.graphql
Or string[]
to point to multiple files:
documents:
- my-query.graphql
- my-other-query.graphql
-
Glob Expression#
You can specify a Glob expression in order to load multiple files:
documents: './src/**/*.graphql'
You can also specify multiple Glob expressions as an array:
documents:
- './src/dir1/*.graphql'
- './src/dir2/*.graphql'
You can specify files to exclude by prefixing the Glob expression with !
:
documents:
- './src/**/*.graphql'
- '!*.generated.graphql'
All provided glob expressions are evaluated together. The usage is similar to .gitignore
.
Additionally, you can use code files, and the codegen will try to extract the GraphQL documents from it:
documents:
- './src/*.jsx'
The codegen will try to load the file as an AST and look for exact GraphQL operations strings. Still, if it can't find those, it will try to require
the file and look for operations in the default export.
You can disable the require
if it causes errors for you (for example, because of different module system):
documents:
- './src/*.jsx':
noRequire: true
Your operations should be declared as template strings with the gql
tag or with a GraphQL comment (const myQuery = /* GraphQL*/`query { ... }`
). This can be configured with pluckConfig
(see below).
-
String#
You can specify your GraphQL documents directly as an AST string in your config file. It's very useful for testing.
documents:
- 'query { f1 }'
- 'query { f2 }'
GraphQL Tag Pluck#
GraphQL Code Generator uses graphql-tag-pluck
internally to extract GraphQL documents from your code file.
If you are pointing to a code file (such as .js
or .jsx
), GraphQL will try to look for usages of gql
tag, or string literals that are using magic GraphQL comment (/* GraphQL */
), for example:
import React from 'react'
import { gql } from 'graphql-tag'
// This will work
const MY_QUERY = gql`
query myQuery {
getSomething {
id
}
}
`
// This will also work
const MY_QUERY = /* GraphQL */ `
query myQuery {
getSomething {
id
}
}
`
// ... some components code ...
By default, it has a predefined list of popular gql
tags to look for, in order to make sure it's not trying to extract an invalid or unrelated string. The default list could be found here
You can add custom tags if you need by using pluckConfig
on the root level on your config file:
pluckConfig:
modules:
- name: my-custom-module
identifier: gql
You can also customize globally used identifiers, like that:
pluckConfig:
globalGqlIdentifierName:
- gql
- graphql
- myCustomGlobalGqlTag
And you can customize the magic GraphQL comment by doing:
pluckConfig:
gqlMagicComment: customcomment
Custom Document Loader#
Suppose your schema has a different or complicated way of loading. In that case, you can specify a custom loader with the loader
field.
documents:
- '**/*.graphql':
loader: my-documents-loader.js
Your custom loader should export a default function that returns a DocumentNode
. For example:
const { parse } = require('graphql')
const { readFileSync } = require('fs')
module.exports = (docString, config) => {
return parse(readFileSync(docString, { encoding: 'utf-8' }))
}
The second parameter passed to the loader function is a config object that includes a pluginContext
property. pluginContext
is passed to any executed plugins, so it can be modified by the loader to pass any additional information to those plugins.