Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub

gatsby-plugin-typegen

Package version Npm downloads Integration Language grade: JavaScript License Backers

All Contributors

TypeScript/Flow code generation for GatsbyJS queries.

Features

  • Schema extraction
  • Plugin documents extraction
  • Generates type definitions for TypeScript & Flow, using graphql-codegen
  • Auto-fixing <StaticQuery> and useStaticQuery() in code with generated type name.
  • Integrates GatsbyJS project with GraphQL & TypeScript ecosystem.

However, GatsbyJS provides builtin typegen feature since v4.15+. See discussion.

I strongly recommend to use the official feature instead of this plugin. If you would like to experiment with other typegen use cases with this plugin, please leave your idea!

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.js.flow`,
  },
}

Add generated typedefs to .flowconfig:

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

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.

  1. Install the VSCode GraphQL 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,
            },
            emitPluginDocument: {
              'src/__generated__/gatsby-plugin-documents.graphql': true,
            },
          },
        },
      ],
    };
  3. 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,
          },
        },
      },
    }
  4. 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 GCG. You cannot customize plugins and its options because this plugin is built for ONLY GatsbyJS queries.

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

Changelog

v3.1.0

  • Added Gatsby v5 to the peerDependencies range.
  • Deprecated commentDescriptions option in emitSchema in favor of GraphQL.js v16.

v3.0.0

  • Added support for GatsbyImageData scalar. (See gatsbyjs/gatsby#35683)
  • [BREAKING CHANGE] nullable fields are typed as T | null, instead of T | undefined (which was inaccurate).
  • The output is now stable, no more dev-only fields, no more randomly-sorted definitions.
  • autoFix option is renamed to autofix. Previous option will be removed in v4.
  • emitPluginDocuments option is renamed to emitPluginDocument. Previous option will be removed in v4.
  • Fixed bunch of bugs (#138).
  • Introduced a very predictable & debuggable scheduler built on top of XState.

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

📖

Antonio Aznarez

💻

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

Backers

Thank you to all our backers! 🙏 [Become a backers]

Sponsors

Does your company has large GatsbyJS codebase? Consider supporting this project! It can help contributors to develop tools and discover patterns so that we can use GatsbyJS more soundly. [Become a sponsor]

Acknowledgements

© 2023 Gatsby, Inc.