website/src/pages/docs/config-reference/documents-field.mdx
import { Callout } from '@theguild/components'
documents fieldThe 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.
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
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
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
The following can be specified as a single value or as an array with mixed values.
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
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
<Callout>All provided glob expressions are evaluated together. The usage is similar to .gitignore.</Callout>
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
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 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
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'))
}