Codegen
DocumentationAdvanced UsageDocument Transform

Document Transform

Document transform is a feature that allows you to modify documents before they are used by plugins. You can use functions passed to the documentTransforms option to make changes to GraphQL documents.

Basic Usage

Document transform has transform function.

Let’s specify an object containing those functions as the documentTransforms option as follows:

import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [
        {
          transform: ({ documents }) => {
            // Make some changes to the documents
            return documents
          }
        }
      ]
    }
  }
}
export default config

For instance, to remove a @localOnlyDirective directive from documents, you can write the following code:

import type { CodegenConfig } from '@graphql-codegen/cli'
import { visit } from 'graphql'
 
const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [
        {
          transform: ({ documents }) => {
            return documents.map(documentFile => {
              documentFile.document = visit(documentFile.document, {
                Directive: {
                  leave(node) {
                    if (node.name.value === 'localOnlyDirective') return null
                  }
                }
              })
              return documentFile
            })
          }
        }
      ]
    }
  }
}
export default config

How to specify by name

The document transform can also be specified by file name. You can create a custom file and pass it to documentTransforms.

Let’s create a file named ./my-document-transform.js:

module.exports = {
  transform: ({ documents }) => {
    // Make some changes to the documents
    return documents
  }
}

Then, you can specify the file name as follows:

import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: ['./my-document-transform.js']
    }
  }
}
export default config

Configuration

If you want to change the behavior of a document transform at runtime, you can simply prepare a function that generates the document transform and write the configuration in its argument.

import type { CodegenConfig } from '@graphql-codegen/cli'
 
const generateDocumentTransform: (config: { queryName: string }) => Types.DocumentTransformObject = ({ queryName }) => {
  return {
    transform: ({ documents }) => {
      // Modify something in documents using `queryName`.
      return documents
    }
  }
}
 
const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [generateDocumentTransform({ queryName: 'test' })]
    }
  }
}
export default config

If you want to specify the document transform by file, do the following:

import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [
        {
          './my-document-transform.js': {
            queryName: 'test'
          }
        }
      ]
    }
  }
}
export default config

In this case, you can retrieve the queryName from the config argument of the transform function as follows:

module.exports = {
  transform: ({ documents, config }) => {
    // Modify something in documents using `config.queryName`.
    return documents
  }
}
ProfilerVSCode Extension