• Docs
• Writing Plugins
• Contributing

Contributing

When your new plugin is ready, you can either:

• maintain it in your repo and npm package
• contribute and make it part of the GraphQL Code Generator repo

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

• GitHub Account
• Git
• Node.js (v10/v12/v13)
• Yarn (v1)
• Any code editor (we recommend VSCode)

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 in GitHub; this will allow you to make changes and push them quickly later.

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

It's also recommended to create a new Git branch at this point, from master 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

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.

{
  "name": "@graphql-codegen/MY_PLUGIN_NAME"
}

2. Make sure that the version is aligned with all other existing packages.

{
  "version": "X.Y.Z"
}

3. Make sure that you have the following scripts configured;

{
  "scripts": {
    "lint": "eslint **/*.ts",
    "test": "jest --no-watchman --config ../../../../jest.config.js"
  }

4. Make sure your basic plugin dependencies are configured this way:

{
  "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"
  }
}

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'}!`
}

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:

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.yml, and run yarn generate:examples in the project root directory to run it.

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:

/**
 * 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
}

2. 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
  }
  // …
]

10. Website & Plugins Hub

To add your plugin to the website and Plugins page, add your plugin package information in website/src/lib/plugins.ts:

const PACKAGES: Package<Tags>[] = [
  {
    identifier: 'my-plugin', // package id, will be used for the url slug
    title: 'my-plugin', // page title
    npmPackage: '@graphql-codegen/my-plugin', // name of the npm package
    icon: codegenIcon, // you can specify a custom icon, or use codegen's
    tags: ['plugin', 'utilities'] // add tags for the search engine
  }
  // …
]

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

Your plugin page should be available in http://localhost:3000/plugins/my-plugin

11. Add it to the live demo (optional)

Our website has a live demo on the main page for most plugins, and you can add it there if you wish.

To add a new example to the live demo, start by making sure that your plugin package is available for the website:

1. Edit website/package.json and add your plugin package under dependencies.
2. Add your example under website/src/components/live-demo/examples.ts - you can add a custom schema, documents and configuration.