Community Plugin

gatsby-plugin-typegen

Modifications that have been made while official V3 is in progress:

For flow language JSON scalar is now any instead of never.
Updated @graphql-codegen/flow to v1.18.5 to fix issues with missing type prefixes inside arrays.
Removed $ from types prefix for flow language.

License

High-performance TypeScript/Flow code generation for GatsbyJS queries.

Features

Schema extraction
Plugin documents extraction
Generates type definitions using graphql-codegen
Auto-fixing <StaticQuery> and useStaticQuery() in code with generated type name.
Integrates GatsbyJS project with GraphQL & TypeScript ecosystem.
Provides type definitions for the schema customization.
Provides utility types for gatsby-node.js.

Demo

Demonstration of auto-fixing

Install

yarn add gatsby-plugin-typegen

# or
# npm install --save gatsby-plugin-typegen

How to use

// In your gatsby-config.js
plugins: [`@ofqwx/gatsby-plugin-typegen`]

Example of type-safe usage

import type { PluginOptions as TypegenPluginOptions } from 'gatsby-plugin-typegen/types';

type Plugin = (
  | string
  | { resolve: string, options: object }
  | { resolve: `@ofqwx/gatsby-plugin-typegen`, options: TypegenPluginOptions }
);

const plugins: Plugin[] = [
  {
    resolve: `@ofqwx/gatsby-plugin-typegen`,
    options: {
      // ... customize options here
    },
  },
];

module.exports = {
  plugins,
};

Change the output path

{
  options: {
    outputPath: `src/__generated__/gatsby-types.d.ts`,
  },
}

Switch to Flow

{
  options: {
    language: `flow`,
    outputPath: `src/__generated__/gatsby-types.flow.js`,
  },
}

Add generated typedefs to .flowconfig:

[lib]
./src/__generated__/gatsby-types.flow.js

Emit schema as GraphQL SDL

{
  options: {
    emitSchema: {
      'src/__generated__/gatsby-schema.graphql': true,
    },
  },
}

GatsbyJS schema visualized

Visualized via GraphQL Voyager.

VSCode extension

You can use the VSCode GraphQL with a graphql-config file.

Install the VSCode GraphQL extension.

Configure plugin to emit schema and plugin documents.

// gatsby-config.js

module.exports = {
  plugins: [
    // ...
    {
      resolve: `gatsby-plugin-typegen`,
      options: {
        emitSchema: {
          'src/__generated__/gatsby-introspection.json': true,
        },
        emitPluginDocuments: {
          'src/__generated__/gatsby-plugin-documents.graphql': true,
        },
      },
    },
  ],
};

Create graphql.config.js file in project root or supported graphql-configs.

// graphql.config.js

module.exports = {
  schema: ["src/__generated__/gatsby-introspection.json"],
  documents: ["src/__generated__/gatsby-plugin-documents.graphql"],
  extensions: {
    endpoints: {
      default: {
        url: "http://localhost:8000/___graphql",
        headers: { "user-agent": "JS GraphQL" },
        introspect: false,
      },
    },
  },
}

Reload VSCode, gatsby develop to make queries in VSCode.

VSCode extension preview

ESLint

You can use the extracted schema file for eslint-plugin-graphql!

// gatsby-config.js

module.exports = {
  plugins: [
    // ...
    {
      resolve: `gatsby-plugin-typegen`,
      options: {
        emitSchema: {
          'src/__generated__/gatsby-introspection.json': true,
        },
      },
    },
  ],
};

// .eslintrc.js

const path = require('path');

module.exports = {
  plugins: [
    'graphql'
  ],
  rules: {
    'graphql/template-strings': ['error', {
      env: 'relay',
      tagName: 'graphql',
      schemaJsonFilepath: path.resolve(__dirname, 'src/__generated__/gatsby-introspection.json'),
    }],
  },
};

TypeScript plugin

The extracted schema file can also be used for ts-graphql-plugin. Using the config defined in Emit schema as GraphQL SDL:

// tsconfig.json
{
  "compilerOptions": {
    // ...
    "plugins": [
      {
        "name": "ts-graphql-plugin",
        "schema": "src/__generated__/gatsby-schema.graphql",
        "tag": "graphql"
      }
    ]
  },
}

demo with ts-graphql-plugin, it shows type hints, auto suggestions, type errors on GraphQL tag

Available options

Checkout the full documentation of plugin options from src/types.ts.

Disclaimer

This plugin is a bit opinionated about how integrate GatsbyJS and codegen.

You cannot customize plugins and its options of graphql-codegen because this plugin is built for ONLY GatsbyJS.

If you wanna use codegen with other plugins (e.g. React Apollo), you can use @graphql-codegen/cli for it.

Or gatsby-plugin-graphql-codegen gives you a more flex options.

Troubleshooting

`Error: Cannot use GraphQLSchema "[object GraphQLSchema]" from another module or realm.`

See https://github.com/cometkim/gatsby-plugin-typegen/issues/120

Changelog

v2.2.4

Fix misconfigured codegen options (#$81)

v2.2.3

Allow React v17 as peer dependency (#140)

v2.2.2

Fix missing options (#$81)

v2.2.1

Fixes bug caused by upstream behavior change (#93)

v2.2.0

Use union types instead of enum values (#78)
Emit schema when add a new frontmatter field (#82)

v2.1.0

Use string type for the GatsbyJS’s Date scalar by default. (#73)
Allow to add type mappings for custom scalars. (#73)
Avoid using unstable API internally (#71, original issue: #54)

v2.0.1

Fix multiple query definitions in plugin documents on Windows (#66, original issue: #44)

v2.0.0

[BREAKING CHANGE] Generated types are now using global declaration with a namespace (default is GatsbyTypes).
Fixed an issue where the insert types function only worked when documents were changed. (#43)

v1.1.2

Export inline fragment subtypes. (#45)
Insert eslint-disable comment on top of generated file. (#37)

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Hyeseong Kim} 🚧 💻 📖 🐛 🤔 👀	_{Richard Sewell} 💻 🚧	_{Derek Nguyen} 💻 🚧	_{Vincent Khougaz} 💻	_{JongChan Choi} 💻 📖	_{John Rom} 💻	_{Jeremy Albright} 💻 🐛 🤔 👀
_{Lars Francke} 📖	_{Piotr Monwid-Olechnowicz} 📖	_{Edward Kim} 🐛 💻	_{Emily Marigold Klassen} 📖	_Thijmen 🚧	_{Ricardo Gallardo} 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Acknowledgements

graphql-code-generator by @dotansimha
The where this plugin started from.
gatsby-plugin-graphql-codegen by @d4rekanguok
Has almost same goal, but little bit different how handle GraphQL documents. @d4rekanguok also makes great contribution to this plugin as well!
gatsby-plugin-extract-code by @NickyMeuleman
Gives me an idea of ESLint integraiton.