@toptal/davinci-graphql-codegen

⚛ GraphQL Codegen

GraphQL Codegen is a library developed by Toptal with the idea in mind of improving DX when generating types for your application. Easy to configure (almost no-config) and extend, and easy to import and use. With this library you'd be able to generate types for all your schemas without worring much about implementation details, and if you need to customize or use a specific plugin to suit your needs, it would be piece of cake just by adding the plugin name to the config (package specific or global).

🛠 Generating Schema Types

In order to generate schema types for your GraphQL Gateway the reccomended way is that you create a lib/graphql package in your monorepo and create a codegen.json file were you will store some configuration needed for later usage. This file will contain a structure like the following¹:

[
  {
    "schema": [
      "gs://gqlgw-introspection/staging_talent_schema.graphql",
      "./libs/graphql/extensions.graphql"
    ],
    "target": "talent"
  },
  {
    "schema": "gs://gqlgw-introspection/staging_staff_schema.graphql",
    "target": "staff"
  },
  {
    "schema": "gs://gqlgw-introspection/staging_lens_schema.graphql",
    "target": "lens"
  }
]

The array contains many objects with the following shape:

{
  schema: string
  target: string
}

The schema property will point to a protocol (https:// or gs://) or a relative path where the schema will be fetched from. The target property will indicate where the schema is going to be stored.

¹ This structure might be subject to change in a future iteration of this project

After creating the package and applying the default configurations you should add Davinci as a dependency of @toptal/modularity-template-graphql (it's how we name this package within our monorepo to resolve to libs/graphql) and add this script to your package.json:

"generate-schema": "davinci-graphql-codegen generate-schema"

When you run the above command, it will iterate over the schemas you have configured in your codegen.json and then create those schemas locally for you to commit to your repo, and then make use of them for generating operation types.

🛠 Generating Operation Types

In order to generate operation types for your GraphQL Gateway, you'd need to add this script to your package.json.

"generate-operations": "davinci-graphql-codegen generate-operations"

Then create a codegen.json file at the root folder of your package that contains the following data/structure:

{
  "schema": "@toptal/modularity-template-graphql/talent",
  "documents": "src/**/*.gql"
}

The schema property in the codegen.json file is where this utility is going to go search for your schema, parse it and then generate the appropriate typescript types for all your GraphQL operations. In this example we're telling the utility to use the schema located at @toptal/modularity-tempalte-graphql, which is the package were we will store our schemas. In this example, @toptal/modularity-template-graphql/talent will resolve to libs/graphql/talent, but it can be any package were you'd like to store your schemas at.

The documents property is a glob pattern that tells this utility where your GraphQL operations are located. Please note that this glob pattern does not start with ./ as we use process.env.INIT_CWD to resolve where this utility was launched from and therefore, using ./src/**/*.gql will break the implementation and won't be able to resolve your files.

⚙️ Customizing GraphQL Codegen

GraphQL Codegen is an extensible and configurable tool that gives you the ability to customize many different things to suit your project needs.

Using a custom codegen.json file

You can customize the codegen.json file that GraphQL Codegen is going to look for. You can do so via CLI with the following command:

yarn davinci-graphql-codegen generate-schema --config=./graphql/codegen-schema.json

The above script will search for codegen-schema.json within ./graphql.

Using custom config

To override default configuration, preset, presetConfig, plugins, and config options can be added to codegen.json.

// codegen.json
[
  {
    "schema": "@toptal/modularity-template-graphql/talent",
    "documents": "src/**/*.gql",
    "preset": "...",
    "presetConfig": { ... },
    "plugins": [ ... ],
    "config": { ... }
  }
]

Please see the https://the-guild.dev/graphql/codegen/docs/config-reference/codegen-config for more information about these options.

Customizing the extension of generated files

When generating operations, we have set a default setting that generates your operation types within a file named the same as where your query or mutation is and it will have the .ts extension. This is due to that the default extension for your queries or mutations should be .graphql. But you might have your query within a .ts file that comes with, for instance, a hook that makes use of this query, and if you'd run GraphQL Codegen Operations as is, you'll have that .ts file ovewriten. But you can avoid this conflict via CLI with the following command:

davinci-graphql-codegen generate-operations --extension=.types.ts

The above script will tell GraphQL Codegen that when generating operations, you'd like it to generate your types with the .types.ts extension so it won't conflict with your already existing .ts file which contains more than your query or mutation.

Plugins

GraphQL Codegen has various in-house developed plugins that will make our development experience even more easier and delighful. Here you can find a list of the current plugins available:

• Fragment Resolver - Resolve fragment imports so your generated types that import fragments are safely generated without any issue.