Skip to main content
Community Plugin
View plugin on GitHub
See starters using this

gatsby-plugin-typegen

Package version Npm downloads Actions Status Language grade: JavaScript License

All Contributors

Watch your queries and automatically generates TypeScript/Flow definitions out-of-box.

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: [`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: `gatsby-plugin-typegen` options: TypegenPluginOptions }
);

const plugins: Plugin[] = [
  {
    resolve: `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.

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'),
    }],
  },
};

VSCode extension

I recommend to use Apollo GraphQL extension.

(YES, even this isn’t Apollo project)

  1. Install the extension.
  2. 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,
            },
          },
        },
      ],
    };
  3. Create apollo.config.js file in project root.

    // apollo.config.js
    
    module.exports = {
      client: {
        name: 'your-project-name',
        tagName: 'graphql',
        includes: [
          './src/**/*.{ts,tsx}',
          './src/__generated__/gatsby-plugin-documents.graphql',
        ],
        service: {
          name: 'GatsbyJS',
          localSchemaFile: './src/__generated__/gatsby-schema.graphql',
        }
      },
    }
  4. Reload VSCode & Enjoy!
    VSCode extension preview

TypeScript plugin

TODO: Add config example

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.

Changelog

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):


Richard Sewell

💻 🚧

Derek Nguyen

💻 🚧

Vincent Khougaz

💻

JongChan Choi

💻 📖

John Rom

💻

Jeremy Albright

💻 🐛 🤔 👀

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

Acknowledgements

Docs
Tutorials
Plugins
Blog
Showcase