The Guild LogoThe Guild Monogram

GraphQL Config

Get Started


Config search places#

  • graphql.config.json

  • graphql.config.js

  • graphql.config.cjs

  • graphql.config.ts

  • graphql.config.toml

  • graphql.config.yaml

  • graphql.config.yml

  • .graphqlrc (YAML and JSON)

  • .graphqlrc.json

  • .graphqlrc.toml

  • .graphqlrc.yaml

  • .graphqlrc.yml

  • .graphqlrc.js

  • .graphqlrc.ts

  • graphql property in package.json


The simplest config specifies only schema which points to the source of GraphQL Schema.

schema: ./schema.graphql

Based on the above example you may think GraphQL Config accepts only single graphql files, but it does more than that.

To learn more about possible sources of GraphQL schema read the "Specifying schema" chapter.


Another piece of GraphQL may be operations and fragments. In GraphQL Config we call them documents.

# ... documents: src/components/**/*.graphql

By default, GraphQL Config is able to find and extract documents from graphql files but if you want to extend it with JavaScript and TypeScript files (also tsx and jsx) please read the "Specifying documents" chapter.

Include / Exclude#

When you want to point out files related to the schema (for instance, React components) and make your IDE GraphQL Extension recognize those files, you can include and exlude items:

# ... include: src/components/**/*.jsx exclude: src/components/__ignored__/**/*.jsx

Remember that all files specified in schema or documents are included by default.


In order to pass information to GraphQL Config's consumers (like IDE extensions, Node libraries), you can use an extensions section that is a key-value object.

schema: './schema/*.graphql' extensions: codegen: generates: ./src/types.ts: plugins: - typescript - typescript-resolvers

Now GraphQL Code Generator is able to consume that data.


GraphQL Config allows you to define multiple projects within the same config file.

Consider, for instance, writing the following configuration:

schema: './schema.graphql' documents: './src/components/**/*.graphql'

This basically creates a singular, default project. In order to extend configuration to multiple projects, you can use the following approach:

projects: foo: schema: './packages/foo/schema.graphql' documents: './packages/foo/src/components/**/*.graphql' bar: schema: './packages/bar/schema.graphql'

It's also possible to define many projects where one is the default. You can simply add default as that project's name:

projects: default: schema: './packages/foo/schema.graphql' documents: './packages/foo/src/components/**/*.graphql' bar: schema: './packages/bar/schema.graphql'