So now when your new plugin is ready, you can either maintain it in your own repo and npm package, or you can contribute and make it part of the GraphQL Code Generator repo.
Our repository contains plugins for all languages and platforms, and if your plugin could be helpful for other, please consider to create a PR and maintain it in our repo. This will also promise to run your tests against the latest core changes, and make sure that there are no breaking changes that effect your plugin.
To be able to clone, build and develop codegen, you'll need to have the following installed:
GraphQL Code Generator is using the following stack to manage the source code:
- TypeScript - for writing the code
- Bob - for building, bundling and development workflow
- 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 easily 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
3. Install Dependencies
GraphQL Code Generator is built as a monorepo, using Yarn Workspaces, so it means that all scripts and dependencies are located in the root
package.json of the project.
So 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:
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 thw following scripts from the root directory:
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:
- Make sure the package name starts with
- Make sure that the version is aligned with all other existing packages.
The current version of the codegen is:
- Make sure that you have the following
This will make sure that your plugin is compatible with our build and test system.
- Make sure your basic plugin dependencies are configured this way:
graphqlmust be a devDependency in order to allow develoeprs to choose their own version.
tslibis required to compile plugins.
@graphql-codegen/plugin-helperscontains 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 run the following command again, in the root direcory:
6. Create your plugin
To create your new plugin, simply create
src/index.ts in your plugin directory, and start with the following:
schemais the merged
GraphQLSchemaobject, from all sources. this will always be available for plugin.
documentsis an array of GraphQL operations (query/mutatation/subscription/fragment). This is optional, and you can use it only if your plugin needs it.
configis the merged configuration passed in the
.yamlconfiguration file of the codegen.
7. Test your plugin
To test your plugin, create a test file -
tests/plugin.spec.ts with the following content;
Now, to make sure it works, run the following in your plugin directory:
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.
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:
- Add JSDoc annotations to your config object, it can also include default value, examples and type:
./website/generate-config.js and add a record to the mapping in that filee, point the file with the configuration annotation, and the output file:
Now, navigate to the
website directory and run
yarn generate:config-docs -this will take a minute, and it will generate the
.md for all plugins. You should find your
my-plugin.md file under
yarn start to run the website. You markdown file is loaded, but it's not displayed yet, so let's create a new page for it first.
website/docs/plugins/ and add the following content to it, and include the generated configuration API reference:
Your plugin page should be available in:
Now, just add it it to the website sidebar by updating
10. Add it to the live demo (optional)
Our website has a live demo in 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:
website/package.jsonand add your plugin package under
website/src/components/live-demo/plugins.jsand add a mapping for the name of your plugin and it's package. This is required in order to have lazy loading and dynamic imports in our website.
Now, add your example under
website/src/components/live-demo/examples.js - you can add a custom schema, documents and configuration.