GraphQL Codegen for Frontend

Photo by charlesdeluvio on Unsplash

As a frontend developer using TypeScript, you want to ensure your code is type safe.

You also use a GraphQL schema as the source of truth and a software contract between the frontend and backend and you may have multiple backend services you will have a federate graph constructed from sub graphs (see Apollo Federation).

from GraphQL schema to TypeScript types

The GraphQL schema represents a strongly type software contract with good separations of concerns and Command Query Responsibility Segregation (CQRS).

It is possible and desirable to generate TypeScript types from your schema using the GraphQL Code Generator. It can generate:

• types from the schema
• operations from query definitions in code

The generated types and operations are used for type-safe front-end code.

Discussion

graphql-codegen is a Development/Build tool that generates code from your GraphQL schema and GraphQL operations, it is super easy to customize with plugins, and is not needed in production.

GraphQL Code Generator is a plugin-based tool that helps you get the best out of your GraphQL stack.

From back-end to front-end, GraphQL Code Generator automates the generation of:

Typed Queries, Mutations and, Subscriptions for React, Vue, Angular, Next.js, Svelte, whether you are using Apollo Client, URQL or, React Query.

Typed GraphQL resolvers, for any Node.js (GraphQL Yoga, GraphQL Modules, TypeGraphQL or Apollo) or Java GraphQL server.

Fully-typed Node.js SDKs, Apollo Android support, and more!

Installation

Add both the graphql and @graphql-codegen/cli packages in the project's dependencies with

npm i graphql
npm i -D typescript @graphql-codegen/cli

OR

yarn add graphql
yarn add --dev typescript @graphql-codegen/cli

See: Installation instructions

Generation workflow

GraphQL Code Generator should be integrated as part of the development workflow.

"codegen": "graphql-codegen --config codegen.yaml"

codegen should be run when the schema is changed

Line 5: codegen entry in the scripts section of package.json runs graphql-codegen CLI using the configuration file codegen.ts

{
  ...
  "scripts": {
    ...
    "codegen": "graphql-codegen --config codegen.yaml"
    ...
  },
  ...
  "devDependencies": {
    ...
    "@graphql-codegen/cli": "^3.2.2",
    "@graphql-codegen/typescript": "^3.0.2",
    "@graphql-codegen/typescript-apollo-angular": "^3.5.6",
    "@graphql-codegen/typescript-operations": "^3.0.2",
    ...
    "typescript": "~4.9.4"
  }
}

Configuration

A configuration file defines how and what graphql-codegen will generate.

The configuration uses the schema definition as the primary input; it can read one or more SDL files or a URL of a running GraphQL server such as Apollo Router.

Optionally, graphql-codegen can be configured to read front-end queries, mutations and subscriptions defined in code or files to generate typesafe parameters for GraphQL operations.

The recommended plugins for Front-end development are:

• typescript — generates types, enums, etc from the schema definitions
• typescript-operations — generates types for GraphQL operations defined in code files

Configuration file using YAML

Line 1 — input schema as glob or URL

Line 2 — files containing frontend queries, mutations and subscriptions. These operations can be embedded in your code or in separate files dedicated to GraphQL operations.

Line 4 — output file

Line 5 — plugins

Lines 19–13: map scalars defined in the schema to TypeScript types e.g DateTime to Date

Output

The output is one or more ts files containing the type definitions. The above example specifies a single file (which is the easiest). The output is source code for the application; it should be compiled like any other source code.

It is very important that you do not modify the generated output by hand; ALWAYS modify the schema and regenerate.

Schema definition language

TypeScript generated from the schema

Example Usage

In this example, three generated types are used:

• NewAccount — input type for a mutation
• NewAccountMutation — the type describing the shape newAccount mutation result.
• NewAccountMutationVariables — the type defining the variables for the newAccount mutation

GraphQL schema and Mutation operation

Generated TypeScript operations

How they are used in an Angular component

The function createAccount creates a new account using a mutation.

Lines 5–10 set values in the NewAccount generated type.

Line 12 invokes the mutate method on the Apollo Client with the generics: NewAccountMutation and NewAccountMutationVariables.

These types were generated from the schema definition using the typescript-operations plugin, and they shape the returned object graph and ensure the variables (lines 14–16) are the correct types.

How they are used in a React component

Lines 2–3. defined at the top of a React Functional Component and specify the mutation function addAccount, the operation ACCOUNT_NEW and the operation variables createData , createLoading and createError. Note that the useMutation hook is qualified by the generics CreateAccountMutation and CreateAccountMutationVariables.

Lines 9–29. newAccount function passes a NewAccount object to the invocation of the addAccount function (line 11) with variables and refetch queries.

Conclusion

Using codegen allows you to have type safe GraphQL types in your frontend, ensuring that the GraphQL schema is the source of truth and a good software contract between the frontend and backend.