gatsby-plugin-graphql-codegen

Gatsby Typescript Graphql Codegen

Automatic type generation for your graphql queries via graphql-code-generator

Installation

yarn add typescript gatsby-plugin-graphql-codegen

Add this to your gatsby config like any other plugins:

// gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-graphql-codegen`,
  ]
}

Options

key	default	value
options.codegen	true	enable / disable generating definitions for graphql queries
options.documentPaths	['./src/**/*.{ts,tsx}', './.cache/fragments/*.js', './node_modules/gatsby-*/**/*.js']	The paths to files containing graphql queries. ⚠️ The default paths will be overwritten by the documentPaths you pass in, so please make sure to include all necessary paths ⚠️
options.fileName	graphql-type.ts	path to the generated file. By default, it's placed at the project root directory & it should not be placed into src, since this will create an infinite loop
options.codegenDelay	200	amount of delay from file change to codegen
options.pluckConfig	{ globalGqlIdentifierName: "graphql", modules: [ { name: 'gatsby', identifier: 'graphql' } ] }	options passed to graphql-tag-pluck when extracting queries and fragments from documents
options.failOnError (^2.5.0)	process.env.NODE_ENV === 'production'	Throw error if the codegen fails. By default only apply to production builds.
options.codegenConfig (^2.7.0)	{}	Add config directly to graphql-codegen. These key-value config will be applied to every graphql-codegen plugins. See graphql-codegen docs on the config field
options.codegenPlugins (^2.7.0)	[]	Add additional plugins to graphql-codegen. We use the same format as Gatsby's. See example usage below.
options.additionalSchemas (^2.6.0)	[]	array of additional schemas (other than the schema used by gatsby queries) for which types should be generated for. This is useful when you use client-side queries (e.g. with apollo-client) where you are querying another schema/endpoint

Additional Schema Options (for options.additionalSchemas)

key	default	value
key	-	an unique key used internally by this plugin to identify different schemas
fileName	graphql-types-${key}.ts	path to the generated file for this schema. By default, it's placed at the project root directory & it should not be placed into src, since this will create an infinite loop
documentPaths	value of options.documentPaths	The paths to files containing graphql queries. See also options.documentPaths
pluckConfig	-	options passed to graphql-tag-pluck when extracting queries and fragments from documents
schema	-	additional schema to process. Can either be an url, a path to a local schema definition (both .json and .graphql are supported) or an inline definition. See also https://github.com/ardatan/graphql-toolkit#-schema-loading
codegenConfig (^2.7.0)	{}	See codegenConfig above
codegenPlugin (^2.7.0)	{}	See codegenPlugin above

Example Setups

Normal Usecase

Set it & forget it

exports.default = {
  plugins: [
    `gatsby-plugin-graphql-codegen`,
  ]
}

Custom Filename & Location

exports.default = {
  plugins: [{
    resolve: `gatsby-plugin-graphql-codegen`,
    options: {
      fileName: `./gatsby-graphql.ts`,
    }
  }]
}

Gatsby-node.ts

You have queries in your gatsby-node? We can take care of that. The experience is not 100% right now, but that'll change soon!

exports.default = {
  plugins: [{
    resolve: `gatsby-plugin-graphql-codegen`,
    options: {
      fileName: `./gatsby-graphql.ts`,
      documentPaths: [
        './src/**/*.{ts,tsx}',
        './node_modules/gatsby-*/**/*.js',
        './gatsby-node.ts',
      ],
    }
  }]
}

Customize Graphql Codegen

You want to pass additional config to graphql-codegen:

// additional plugins
import { plugin as resolverPlugin } from '@graphql-codegen/typescript-resolvers'

exports.default = {
  plugins: [{
    resolve: `gatsby-plugin-graphql-codegen`,
    options: {
      codegenConfig: {
        // key-value configs that will be applied to every plugins.
        // Note: The example below is completely unnecessary, just a demonstration.
        typesPrefix: 'Hi' // -> import { HiImageQuery } from '../../graphql-types'
      },
      codegenPlugins: [{
        // built-in plugin. 
        // Use `typescript` for `@graphql-codegen/typescript`
        // and `operations` for `@graphql-codegen/typescript-operations`
        resolve: 'typescript',
        options: {
          namingConvention: `lower-case#lowerCase`,
        }
      },{
        // additional plugin
        resolve: resolverPlugin,
        options: {
          typesPrefix: 'I'
        }
      }]
    }
  }]
}

Dual-Schema Setup

If you use graphql on the client side, this is for you.

exports.default = {
  plugins: [{
    resolve: `gatsby-plugin-graphql-codegen`,
    options: {
      additionalSchemas: [{
        key: 'pokemon',
        fileName: './graphql-pokemon.ts',
        schema: 'https://graphql-pokemon.now.sh/',
        pluckConfig: {
          // config to ensure only queries using the `gql` tag are used for this schema
          globalGqlIdentifierName: 'gql',
          modules: [
            {
              name: 'graphql-tag',
              identifier: 'gql',
            },
          ],
        },
      }],
    }
  }]
}

Code generation

By default, this plugin will build typing for your queries automatically to graphql-types.d.ts on every edit. Please note that the definition file should not be placed inside src since this triggers a never ending loop during development.

In order to take advantage of the generated code, user needs to name their query:

// src/pages/index.tsx

  export const pageQuery = graphql`
-   query {
+   query BlogIndex {
      site {
        siteMetadata {
          title
        }
      }
  ...

...and import it from the generated type file:

// src/pages/index.tsx

import { PageProps } from "gatsby";
import { BlogIndexQuery } from '../graphqlTypes'

const BlogIndex: React.FC<PageProps<BlogIndexQuery>> = ({ data, location }) => {
  ...
}