Catch the highlights of GraphQLConf 2023! Click for recordings. Or check out our recap blog post.
Docs
Config Reference
documents field

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:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'http://localhost:3000/graphql',
  documents: 'src/**/*.graphql',
  generates: { './src/types.ts': { plugins: ['typescript', 'typescript-operations'] } }
}
export default config

Output-file level

You can also specify the documents field in your generated file level config:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'http://server1.com/graphql',
  generates: {
    './src/types1.ts': {
      documents: 'src/**/*.graphql',
      plugins: ['typescript', 'typescript-operations']
    }
  }
}
export default config

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:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'http://server1.com/graphql',
  documents: 'src/**/!(*.d).{ts,tsx}'
}
export default config

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:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: 'my-query.graphql'
  // ...
}
export default config

Or string[] to point to multiple files:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['my-query.graphql', 'my-other-query.graphql']
  // ...
}
export default config

  • Glob Expression

You can specify a Glob expression in order to load multiple files:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: './src/**/*.graphql'
  // ...
}
export default config

You can also specify multiple Glob expressions as an array:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['./src/dir1/*.graphql', './src/dir2/*.graphql']
  // ...
}
export default config

You can specify files to exclude by prefixing the Glob expression with !:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['./src/**/*.graphql', '!*.generated.graphql']
  // ...
}
export default config
💡
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:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx']
  // ...
}
export default config

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):

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: {
    './src/*.jsx': {
      noRequire: true
    }
  }
  // ...
}
export default config
💡

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.

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['query { f1 }', 'query { f2 }']
  // ...
}
export default config

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:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx'],
  pluckConfig: {
    modules: [
      {
        name: 'my-custom-module'
        identifier: 'gql'
      }
    ]
  }
  // ...
}
export default config

You can also customize globally used identifiers, like that:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx'],
  pluckConfig: {
    globalGqlIdentifierName: ['gql', 'graphql', 'myCustomGlobalGqlTag']
  }
  // ...
}
export default config

And you can customize the magic GraphQL comment by doing:

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx'],
  pluckConfig: {
    gqlMagicComment: 'customcomment'
  }
  // ...
}
export default config

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.

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  // ...
  documents: {
    './src/*.jsx': {
      loader: 'my-documents-loader.js'
    }
  }
  // ...
}
export default config

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'))
}
💡

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.

schema fieldplugin config