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 community repo (dotansimha/graphql-code-generator-community)

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:

• GitHub Account
• Git
• Node.js (v16+)
• 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 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

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

/**
 * 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. Feature your plugin on the Plugins Hub

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

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.

4. 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