Neoclassical Philosophic Musings

    gatsby-plugin-typegen
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.4 • Public • Published

    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

    • [x] Schema extraction
    • [x] Plugin documents extraction
    • [x] Generates type definitions using graphql-codegen
    • [x] Auto-fixing <StaticQuery> and useStaticQuery() in code with generated type name.
    • [x] 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

    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

    🚧

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

    Acknowledgements

    Install

    npm i gatsby-plugin-typegen

    DownloadsWeekly Downloads

    8,070

    Version

    2.2.4

    License

    MIT

    Unpacked Size

    56.2 kB

    Total Files

    22

    Last publish

    Collaborators

    • cometkim