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

schema field

The schema field should point to your GraphQLSchema - there are multiple ways you can specify it and load your GraphQLSchema.

schema can either be a string pointing to your schema or a string[] pointing to multiple schemas that will be merged.

How to use it?

Root-level

You can specify the schema field in your root level config, as follows:

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

Output-file level

Or, you can specify it per-output file level. This way you can

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

Multiple schemas and client-side schema

You can also specify schema on both levels: root and output-file, and then GraphQL Code Generator will merge both schemas into one:

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

It's also helpful if you have a remote schema from a server and a client-side schema available in your client-side.

Available formats

The following can be specified as a single value or an array with mixed values.

URL

You can specify a URL to load your GraphQLSchema from:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'http://localhost:3000/graphql',
  // ...
};
export default config;

Supported Configuration

headers

You can also specify custom HTTP headers to be sent with the request:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      'http://localhost:3000/graphql': {
        headers: {
          Authorization: 'YOUR-TOKEN-HERE',
        },
      },
    },
  ],
};
export default config;
customFetch

You can specify a custom fetch function for the HTTP request, using the module name you wish to use:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      'http://localhost:3000/graphql': {
        customFetch: 'my-custom-fetch',
      }
    }
  ]
};
export default config;
method

You can specify an HTTP method for the introspection query (the default value is POST).

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      'http://localhost:3000/graphql': {
        method: 'GET',
      }
    }
  ]
};
export default config;
handleAsSDL

Handling the response as SDL will allow you to load schema from remote server that doesn't return a JSON introspection. Example use case is when using schema registry like GraphQL Hive.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      'http://localhost:3000/sdl': {
        handleAsSDL: true,
      }
    }
  ]
};
export default config;

JSON

You can point to a local .json file that contains GraphQL Introspection JSON.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'schema.json',
  // ...
};
export default config;

Local .graphql files

You can point to a single .graphql file that contains the AST string of your schema:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'schema.graphql',
  // ...
};
export default config;

Or, you can point to multiple files using a glob expression (codegen will merge the schema files for you):

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

You can also specify multiple patterns:

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

And, you can specify files to exclude/ignore, using the ! sign:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: ['src/**/*.graphql', '!*.generated.graphql'],
  // ...
};
export default config;
💡
All provided glob expressions are evaluated together. The usage is similar to .gitignore.

Supported Configuration

skipGraphQLImport

By default, codegen skips graphql-import to load all files using glob expressions.

If you are using graphql-import syntax in your schema definitions, you can tell codegen to use those import statements:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      './src/**/*.ts': {
        skipGraphQLImport: true
      },
    },
  ],
};
export default config;
commentDescriptions

When enabled, converts all deprecated forms of GraphQL comments (marked with #) into a GraphQL description (marked with ") during the parsing phase.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      './src/**/*.ts': {
        commentDescriptions: true
      },
    },
  ],
};
export default config;
assumeValidSDL

Set to true to assume the SDL is valid, and skip any SDL syntax validations.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      './src/**/*.ts': {
        assumeValidSDL: true
      },
    },
  ],
};
export default config;

Code Files

You can use code files, and the codegen will try to extract the GraphQL schema from it, based on gql tag:

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

The codegen will try to load the file as an AST and look for exact GraphQL strings, but if it can't find those, it will try to require the file and looks for operations in the default export.

Supported Configuration

noRequire

You can disable the require if it causes errors for you (for example, because of a different module system or missing dependency):

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      './src/**/*.ts': {
        noRequire: true,
      },
    },
  ],
};
export default config;
noPluck

You can disable the AST lookup phase and tell codegen to skip and directly try to require each file:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      './src/**/*.ts': {
        noPluck: true,
      },
    },
  ],
};
export default config;
assumeValid

Set this to true to tell codegen to skip AST validation.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      './src/**/*.ts': {
        assumeValid: true,
      },
    },
  ],
};
export default config;

JavaScript export

You can also specify a code file that exports your GraphQLSchema object as export schema or as default export.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'schema.js'
};
export default config;
const { buildSchema } = require('graphql')
 
module.exports = buildSchema(/* GraphQL */ `
  type MyType {
    foo: String!
  }
 
  type Query {
    myType: MyType!
  }
`)
💡

You can also import from TypeScript files, but don't forget to specify require field.

String

You can specify your schema directly as an AST string in your config file. It's handy for testing.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'type MyType { foo: String } type Query { myType: MyType }'
};
export default config;

GitHub

You can load your schema file from a remote GitHub file using one of the following approaches:

Provide GitHub token in Codegen Config

Provide the GitHub path to your schema and token using the following syntax:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: {
    'github:user/repo#branchName:path/to/file.graphql':
      { token: "<YOUR GITHUB TOKEN>" }
  }
};
export default config;

Then, run codegen:

yarn graphql-codegen

Provide GitHub token via Codegen CLI

Alternatively, you can provide just the GitHub path to your schema:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'github:user/repo#branchName:path/to/file.graphql'
};
export default config;

Then, provide your GitHub token using the GITHU_TOKEN environment variable when running codegen:

GITHUB_TOKEN=<YOUR GITHUB TOKEN> yarn graphql-codegen
💡
You can load from a JSON file, .graphql file, or from a code file containing gql tag syntax.

Git

You can load your schema file from a Git repository using the following syntax:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'git:branch:path/to/file.graphql'
};
export default config;
💡
You can load from a JSON file, .graphql file, or from a code file containing gql tag syntax.

Apollo Engine

You can load your schema from Apollo Engine with the following syntax:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      'apollo-engine': {
        engine: {
          apiKey: 'APOLLO_ENGINE_KEY_ID',
        },
        graph: 'GRAPH_ID',
        variant: 'current',
      }
    }
  ]
};
export default config;

Custom Schema Loader

If your schema has a different or complicated way of loading, you can point to a single code file that works for you.

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      'http://localhost:3000/graphql': {
        loader: './my-url-loader.js',
      }
    },
    {
      'schema.graphql': {
        loader: './my-file-loader.js',
      }
    }
  ],
};
export default config;

Your custom loader should export a default function that returns GraphQLSchema object, or an identifier called schema. For example:

const { readFileSync } = require('node:fs')
const { buildSchema } = require('graphql')
 
module.exports = (schemaString, config) => {
  // Your logic for loading your GraphQLSchema
  return buildSchema(readFileSync(schemaString, 'utf8'))
}
💡

The second parameter passed to the loader function is a config object that includes a pluginContext property. This value is passed to any executed plugins, so the loader can modify them to pass any additional information to those plugins.

Loading API URL from TypeScript file example:

If you store your API config in a file, and don't want to repeat the URL in the codegen config. You can follow the following example:

export const API_URL = 'https://example.com/graphql'
export const PUBLIC_TOKEN = '12345'

Create custom loader file:

import fetch from 'cross-fetch'
import { getIntrospectionQuery, buildClientSchema } from 'graphql'
import { API_URL, PUBLIC_TOKEN } from './config'
 
export default async () => {
  const introspectionQuery = getIntrospectionQuery()
 
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Access-Token': PUBLIC_TOKEN
    },
    body: JSON.stringify({ query: introspectionQuery })
  })
 
  const data = await response.json()
 
  return buildClientSchema(data.data)
}

Add custom loader to your codegen config:

import { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: [
    {
      'my-api': {
        loader: './codegen-loader.ts'
      }
    }
  ]
};
export default config;

Finally, make sure that you have installed ts-node, so TypeScript file can be transpiled before running codegen.

In your package.json script, add -r ts-node/register argument to use ts-node transpiler.

package.json
{
  "scripts": {
    "codegen": "graphql-codegen -r ts-node/register --config codegen.json"
  }
}
codegen.tsdocuments field