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'

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

• 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 { readFileSync } = require('node:fs')
const { parse } = require('graphql')
 
module.exports = (docString, config) => {
  return parse(readFileSync(docString, 'utf8'))
}