Documentation
Writing Plugins
Contributing

Contributing

When your new plugin is ready, you can either:

The GraphQL Code Generator community repository contains plugins for all languages and platforms. If your plugin could be helpful for others, please consider creating a PR and maintaining it in our repo. Doing so will also promise to run your tests against the latest core changes and make sure that no breaking changes affect your plugin.

1. Requirements

To be able to clone, build and develop codegen, you’ll need to have the following installed:

GraphQL Code Generator uses the following stack to manage the source code:

  1. TypeScript - for writing the code
  2. Bob - for building, bundling, and development workflow
  3. Jest - for running tests

2. Fork and Clone

Start by creating a Fork of the dotansimha/graphql-code-generator-community repository; this will allow you to make changes and push them quickly later: dotansimha/graphql-code-generator-community.

Then, use Git to clone your newly created fork repository.

It’s also recommended to create a new Git branch at this point, from main branch.

3. Install Dependencies

GraphQL Code Generator is built as a monorepo, using Yarn Workspaces it means that all scripts and dependencies are located in the root package.json of the project.

Now that you have a local copy of the project, start by installing the dependencies for all packages in the repo, by running the following in the root directory of the project:

yarn
💡

If you make changes, add libraries, or new packages, make sure to install the dependencies again, but always from the root directory, otherwise you’ll break the monorepo structure.

4. Make sure everything works

To test the initial scripts and verify that you have a valid development environment, start by running the following scripts from the root directory:

yarn build
yarn test

The command above will make sure to build all common/core packages, and will make sure that all tests are passing.

5. Add your plugin

To add your plugin, start by creating a directory for it. All existing plugins are located under packages/plugins/ directory, so add it there.

Now, create a simple package.json (or, you can copy from other plugins…)

Make sure to follow the following instructions:

  1. Make sure the package name starts with @graphql-codegen/ prefix.
package.json
{
  "name": "@graphql-codegen/MY_PLUGIN_NAME"
}
  1. Make sure that the version is aligned with all other existing packages.
package.json
{
  "version": "X.Y.Z"
}
💡

The current version of the codegen is: Codegen version

  1. Make sure that you have the following scripts configured;
package.json
{
  "scripts": {
    "lint": "eslint **/*.ts",
    "test": "jest --no-watchman --config ../../../../jest.config.js"
  }
}
💡
This will make sure that your plugin is compatible with our build and test system.
  1. Make sure your basic plugin dependencies are configured this way:
package.json
{
  "dependencies": {
    "@graphql-codegen/plugin-helpers": "X.Y.Z",
    "tslib": "~1.11.1"
  },
  "peerDependencies": {
    "graphql": "^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0"
  }
}
💡

graphql must be a devDependency in order to allow developers to choose their own version.

tslib is required to compile plugins.

@graphql-codegen/plugin-helpers contains helpful types and utils. Make sure it has the same version as your package.

Now that your plugin is configured, you need to make sure Yarn knows about it and links it to the monorepo, so rerun the following command, in the root directory:

yarn

6. Create your plugin

To create your new plugin, create src/index.ts in your plugin directory, and start with the following:

import { PluginFunction, Types } from '@graphql-codegen/plugin-helpers'
 
export type MyPluginConfig = {
  name: string
}
 
export const plugin: PluginFunction<Partial<MyPluginConfig>, MyPluginConfig> = (
  schema: GraphQLSchema,
  documents: Types.DocumentFile[],
  config: TypeScriptDocumentsPluginConfig
) => {
  return `Hello ${config.name || 'anonymous'}!`
}
💡

schema is the merged GraphQLSchema object, from all sources. this will always be available for plugin.

documents is an array of GraphQL operations (query/mutation/subscription/fragment). This is optional, and you can use it only if your plugin needs it.

config is the merged configuration passed in the .yaml configuration file of the codegen.

You can follow the plugin tips in Write Your Plugin, Validate Configuration and Using Visitor sections.

7. Test your plugin

To test your plugin, create a test file tests/plugin.spec.ts with the following content:

plugin.spec.ts
import { plugin } from '../src'
 
describe('My Plugin', () => {
  const schema = buildSchema(/* GraphQL */ `
    type Query {
      foo: String!
    }
  `)
 
  it('Should greet', async () => {
    const result = await plugin(schema, [], {
      name: 'Dotan'
    })
 
    expect(result).toBe('Hello Dotan!')
  })
})

Now, to make sure it works, run the following in your plugin directory:

yarn test

8. Integration

You can also test the integration of your plugin with the codegen core and cli, the integration with other plugins and the output for some complex schemas and operations.

To do that, make sure everything is built by using yarn build in the root directory, then you can use it in ./dev-test/codegen.ts, and run yarn generate:examples in the project root directory to run it.

If you would like to test “watch mode” in the same way, you can run yarn watch:examples.

9. Documentation

GraphQL Code Generator website has API Reference for all our plugins. Most of the documentation is generated from code, and some of it is written manually.

In order to add it to the website, do the following:

  1. Add JSDoc annotations to your config object; it can also include a default value, examples, and type:
packages/plugins/my-plugin/config.ts
/**
 * My plugin is super cool!!!
 */
export type MyPluginConfig = {
  /**
   * @name name
   * @description This allows you to generate a greeting with a custom name
   * @default anonymous
   *
   * @exampleMarkdown
   * ## Change the name
   * ```yaml
   * generates:
   *   path/to/file.ts:
   *     plugins:
   *       - my-plugin
   *     config:
   *       name: Uri
   * ```
   */
  name: string
}
  1. Open website/src/lib/plugins-docs.ts and add a record to the pluginsConfigurations variable in that file, and point the file with the configuration annotation:
export const pluginsConfigurations: PluginConfig[] = [
  {
    file: '../packages/plugins/my-plugin/config.ts', // file where the config interface/type is located
    identifier: 'MyPluginConfig', // name of the config interface/type
    name: 'my-plugin' // name of your plugin package
  }
  // …
]
💡

Adding your plugin here will automatically include it in the generated config.schema.json that provides VSCode auto-complete (try running yarn generate-json-config to see it in action) and will generate markdown documentation automatically based on your TypeScript types.

10. Feature your plugin on the Plugins Hub

To add your plugin to the Plugins hub, please follow those steps:

Each plugin belongs to a category (ex: @graphql-codegen/typescript-react-apollo belongs to the typescript category).

Please find the proper category for your plugin (usually based on the target language: TypeScript, Flow, Java, etc).

  1. Create a .mdx to the proper folder of website/src/pages/plugins/, under the proper category.

    For example, the @graphql-codegen/typescript-react-apollo plugin has a page at website/src/pages/plugins/typescript/typescript-react-apollo.mdx.

  2. Add your plugin’s package as a dependency of the website/package.json and run yarn install at the root of the repository.

  3. Update the website/src/lib/plugins-docs.ts file by adding your plugin to the pluginsConfigurations array.

You must provide the relative link to your plugin typing definition. You will find examples with the existing plugins.

  1. Each plugin belongs to a category (ex: @graphql-codegen/typescript-react-apollo belongs to the typescript category). Make sure that your plugin is assigned to the proper category by updating the website/src/category-to-packages.mjs file:

Go ahead to website directory and run the website using yarn dev.

Your plugin page should be available in http://localhost:3000/plugins/<category>/<plugin-name>.

Example for @graphql-codegen/typescript-react-apollo: http://localhost:3000/plugins/typescript/typescript-react-apollo