@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 worrying 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 recommended 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 configuration objects specified below (please note that any other configuration options are prohibited):

{
  schema: string
  target: string
  plugins?: Array<any>
  config?: {
    skipTypename?: boolean
    scalars?: Record<string, string>
  }
}

The schema property specifies a protocol (https:// or gs://) or a relative path where the schema will be fetched from.

The target property indicates where the schema is going to be stored.

The plugins property is optional. The property contains array of additional plugins.

The config.skipTypename and config.scalars properties are optional and affect schema generation the same way as documented.

¹ 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 array contains configuration objects specified below (please note that any other configuration options are prohibited):

{
  schema: string,
  documents: string,
  plugins?: Array<string | {
    add: { content: string },
  }>,
  config?: {
    documentMode?: string,
    skipTypename?: boolean,
    skipTypeNameForRoot?: boolean,
    avoidOptionals?: boolean,
    dedupeOperationSuffix?: boolean,
    useTypeImports?: boolean,
    inlineFragmentTypes?: string,
    dedupeFragments?: boolean,
    scalars: Record<string, string>,
  },
}

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.

The plugins property is optional. By default, configuration uses typescript-operations and typed-document-node plugins, and prepends every generated file with /* eslint-disable */ /* ⚠️ THIS IS AN AUTOGENERATED FILE, DO NOT EDIT ⚠️ */ string (set via { add: { content: string } } configuration).

The config property is also optional. See corresponding documentation of typescript-operations and typed-document-node plugins for more information about these options.

GraphQL Codegen uses near-operation-file preset.

⚙️ 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.

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.