GraphQL Codegen blog post & examples @ Medium
What’s new in graphql-code-generator 0.9.0? @ Medium
GraphQL code generator, with flexible support for multiple languages and platforms, and the ability to create custom generated projects based on GraphQL schema or operations.
GraphQL entities are defined as static and typed, which means they can be analyzed and use as a base for generating everything.
This generator generates both models (based on GraphQL server-side schema), and documents (client-side operations, such as query, mutation as subscription).
The codegen let's you either use a predefined template, or write your own.
The predefined templates are common templates that helps GraphQL developers.
For example, if you develop a server-side with TypeScript and GraphQL, you can use the codegen with the TypeScript template to generate Typings for you server side, based on your schema.
If you develop a client-side with TypeScript, Angular and GraphQL, you can use the codegen with the TypeScript template to generate Typings for you client-side, based on your schema and your queries/mutations.
| Language | Purpose | Package Name & Docs |
|---|---|---|
| TypeScript | Generate server-side TypeScript types, and client-side typings | graphql-codegen-typescript-template |
| MongoDB TypeScript Models | Generate server-side TypeScript types, with MongoDB models | graphql-codegen-typescript-mongodb-template |
| XSD | Generate XSD file | graphql-xsd |
| Introspection | Generate Introspection file | graphql-codegen-introspection-template |
If you are looking for the Flow / Swift generators, please note that we will implement it soon again, but you can use 0.5.5 from NPM.
Note: In order to use GraphQL directives feature, please use GraphQL > 0.9.4 as peer dependency for the generator!
To install the generator, use the following:
$ npm install --save-dev graphql-code-generator graphql
// Or, with Yarn
$ yarn add -D graphql-code-generator graphql
Then, install the template package you wish to use, for example:
$ npm install --save-dev graphql-codegen-typescript-template
// Or, with Yarn
$ yarn add -D graphql-codegen-typescript-template
And then to use it, execute it from NPM script, or use $(npm bin)/gql-gen ... from the command line. If you are using Yarn, you can just use yarn gql-gen ...
You can also install it as global NPM module and use it with
gql-genexecutable.
This package offers both modules exports (to use with NodeJS/JavaScript application), or CLI util.
CLI usage is as follow:
$ gql-gen [options] [documents ...]
-
With local introspection JSON file, generate TypeScript types:
$ gql-gen --schema mySchema.json --template graphql-codegen-typescript-template --out ./typings/ "./src/**/*.graphql" -
With local introspection JSON file, generate TypeScript files, from GraphQL documents inside code files (
.ts):$ gql-gen --schema mySchema.json --template graphql-codegen-typescript-template --out ./typings/ "./src/**/*.ts" -
With remote GraphQL endpoint that requires Authorization, generate TypeScript types:
$ gql-gen --schema http://localhost:3010/graphql --header "Authorization: MY_KEY" --template graphql-codegen-typescript-template --out ./typings/ "./src/**/*.graphql"
Note: when specifying a glob path (with
*or**), make sure to wrap the argument with double quotes ("...").
Allowed flags:
| Flag Name | Type | Description |
|---|---|---|
| -s,--schema | String | Local or remote path to GraphQL schema: Introspection JSON file, GraphQL server endpoint to fetch the introspection from, local file that exports GraphQLSchema, JSON object or AST string. |
| -r,--require | String | Path to a require extension, read this for more info |
| -h,--header | String | Header to add to the introspection HTTP request when using remote endpoint |
| -t,--template | String | Template name, for example: "typescript" (not required when using --project) |
| -p,--project | String | Project directory with templates (refer to "Custom Templates" section) |
| --project-config | String | Path to project config JSON file (refer to "Custom Templates" section), defaults to gqlgen.json |
| -o,--out | String | Path for output file/directory. When using single-file generator specify filename, and when using multiple-files generator specify a directory |
| -m,--skip-schema | void | If specified, server side schema won't be generated through the template (enums won't omit) |
| -c,--skip-documents | void | If specified, client side documents won't be generated through the template |
| --no-overwrite | void | If specified, the generator will not override existing files |
| documents... | [String] | Space separated paths of .graphql files or code files (glob path is supported) that contains GraphQL documents inside strings, or with either gql or graphql tag (JavaScript), this field is optional - if no documents specified, only server side schema types will be generated |
This repository includes some examples for generated outputs under dev-test directory.
- Star Wars generated TypeScript output is available here.
- Star Wars generated TypeScript (multiple files) output is available here.
- GitHunt generated TypeScript output is available here.
To use inside an existing project, I recommend to add a pre-build script that executes the code generator, inside you package.json, for example:
{
"name": "my-project",
"scripts": {
"prebuild": "gql-gen ...",
"build": "..."
}
}Some of the generators supports a custom config, which you can specify using gqlgen.json like that:
{
"generatorConfig": {
"printTime": true
}
}Or, you can set the value using environment variables, before executing the codegen, with the CODEGEN_ prefix:
CODEGEN_PRINT_TIME=true gql-gen --template ...
If you with to use this package as a library and execute it from your code, do the following:
import { generate } from 'graphql-code-generator';
function doSomething() {
const generatedFiles = await generate({
template: 'typescript',
url: 'http://127.0.0.1:3000/graphql',
out: process.cwd() + '/models/'
});
}The method generate accepts two parameters: (options: CLIOptions, saveToFile: boolean), and returns Promise<FileOutput[]>.
To create custom template, or generate a whole project from GraphQL schema, refer to Custom Templates Documentation
The generator will automatically executes prettier on the output code, when possible. It will automatically use the correct parser according to the file extensions of the output file.
In case of an error, prettier will be ignored, and will write the file as-is.
If you project has prettier config file, the generator will use it and respect your code-style.
If you are using TypeScript and would like to use your GraphQL Schema from a local file (using --schema), you can use --require to load a require extension.
For example, install ts-node from NPM and use it this way:
gql-gen --require ts-node/register --template typescript --schema ./src/my-schema.ts --out ./src/models/
This way, the file ./src/my-schema.ts is loaded directly as TypeScript file, and you don't need to compile it to plain JavaScript before using it.
If you are using GraphQL with environment different from NodeJS and wish to generate types and interfaces for your platform, start by installing NodeJS and the package as global, and then add the generation command to your build process.
apollo-codegen generates a similar results, but it based on code that generates the results.
This package uses templates (with Handlebars) to generate results, and it basically supports any output because you can simply create you template and then compile it with your GraphQL schema and GraphQL operations and get a more customized result.
This package also allow you to create custom templates, regardless the built-in generators, so you can use your schema as source to any generated result you need.
If you have issues with the generator, feel free open issues in this repository.
If you report a bug or execution issue, please run the generator with DEBUG=true gql-gel ... and provide the debug log.
Feel free to open issues (for bugs/questions) and create pull requests (add generators / fix bugs).
MIT