This article was published on Monday, May 7, 2018 by Dotan Simha @ The Guild Blog
This blog post refers to an outdated version, please check https://the-guild.dev/graphql/codegen
for the latest docs!
The GraphQL codegen library can generate
any code for any language — including type definitions, data models, query builder, resolvers,
ORM code, complete full stack platforms!! and any specific code for your needs.
Not sure what GraphQL Code Generator is? read this!
I'm Excited to Announce a New Version of the GraphQL Code Generator! 🎉🎉🎉
Here are some of the new feature and changes in the new release:
- New CLI util that helps you to write custom templates: now it's much easier to write your own generator template!
- TypeScript & MongoDB template: a new template was added — you can now generate TypeScript models for MongoDB
- Programmatic usage: our can now use it from your code and not just as CLI
- TypeScript template now supports output customization using environment variables.
And also a lot of bugs were fixed.
You can find the full changelog here.
New CLI Util That Helps You to Write Custom Templates
As part of the development, we understood the value of templates sharing between developers. We also
understood that it's difficult to get started with writing your own codegen templates. That's why we
created a new CLI util called codegen-handlebars-templates-scripts.
With these tools, you can easily scaffold, build, test and publish your new template, and share it
with other developers.
To start with the new tool, install it globally:
- Custom output processors: we know that Handlebars isn't for everyone, so now you can write custom processors that does whatever you need
yarn global add codegen-handlebars-templates-scripts
Then, create a directory for your template, and run the init command:
mkdir my-template
cd my-template
codegen-handlebars-templates-scripts init
Now you got a new Codegen template project, so all you have to do it to start writing your template.
If you wish to build it and test it, you can use the predefined commands:
yarn build
yarn test
To get some inspiration, ideas and examples, you can take a look at
the implementation of the TypeScript templates.
TypeScript & MongoDB Template
We also implemented a
new template,
to make it easier for MongoDB developers to integrate the GraphQL Code Generator.
The new template is called graphql-codegen-typescript-mongodb-template and to use it, run the
following:
yarn add -D graphql-codegen-typescript-mongodb-template
gql-gen --template graphql-codegen-typescript-mongodb-template --schema ...
The idea behind the new template is to help MongoDB developer to write better code, and to make sure
their data is type safe.
With this template, you can defined you GraphQL schema in the following format: (don't worry, we
also included the GraphQL @directives for you as part of the package)
type User @entity {
id: String @id
username: String! @column
email: @column
}
And your generated output will be:
import { ObjectID } from 'mongodb'
export interface UserDbObject {
_id: ObjectID
username: string
email?: string | null
}
To read more about the usage and for more examples,
go ahead and read the template's README.
Custom Output Processors
We know that writing templates isn't easy, and we know that not everyone likes to use Handlebars to
write templates, so we made it easier to write your own output processor.
Implementing a custom output processor is easy. All you have to do is to create a JavaScript file
(or any other, and compile it to JS), and use it for your --template flag. Your JS file should use
default export a function that will build the entire output.
The code generator core will make sure to pass everything you need regarding your GraphQL schema and
GraphQL documents.
You can read more about custom output processors here.
Programmatic Usage
Part of the new release is an easier way to use the GraphQL Code Generator programmatically. So if
you want to integrate the codegen into another util — now you can do it!
Just import generate from graphql-code-generator and run it with your options object (you can
also choose whether to write the files to the FS or not):
import { generate } from 'graphql-code-generator'
async function doSomething() {
const generatedFiles = await generate({
template: 'typescript',
url: 'http://127.0.0.1:3000/graphql',
out: process.cwd() + '/models/'
})
}
New Features in TypeScript Template
In this release we did some bug fixes and changes in the TypeScript template: we now generate
nullables and nullable arrays in a better way, and we also fixes some bugs in the generated results.
The TypeScript template now also supports multiple configuration options, so you can customize the
output according to you needs:
printTime - Setting this to true will cause the generator to add the time of the generated
output on top of the file.
avoidOptionals - This will cause the generator to avoid using TypeScript optionals (?), so the
following definition: type A { myField: String } will output myField: string | null instead of
myField?: string | null.
enumsAsTypes - Will generate the declared enums as TypeScript type instead of enums. This is
useful if you can't use .ts extension.
immutableTypes - This will cause the codegen to create immutable types as output, by adding
readonly to the properties and ReadonlyArray.
What's Next?
Our next steps for the GraphQL code generator is to expand the templates collection and to create a
community for sharing templates.
If you wish to help us by writing a template a sharing, feel free to contact us by creating a
new issue in the package repository.
If you already created a template, you can
edit the README file and add it there.
Top comments (0)