Guides

Generated Artifacts

Introduction

When you make a change to your GraphQL schema it is useful to see how exactly this changes the contract of the API, or the associated typings.

GraphQL Nexus takes care of this for you, simply provide a path to where you want these files to be output and it will auto-generate them when the server starts. By default, this only occurs when process.env.NODE_ENV !== "production".

1const schema = makeSchema({
2  types: [
3    /* All schema types provided here */
4  ],
5  outputs: {
6    schema: path.join(__dirname, '../../my-schema.graphql'),
7    typegen: path.join(__dirname, '../../my-generated-types.d.ts'),
8  },
9})

Although your .graphql file is generated, we recommend you check the file into source control. This gives you visibility into how changes in type construction affect the schema consumed by the end-user.

TypeScript Type Generation

This is the most important piece to understand to get the most out of Nexus. It is relevant to JavaScript as well as TypeScript users, as tools like VSCode and // @ts-check can utilize these types to aid in autocomplete or type-checking. A core goal of Nexus is to have the best possible type coverage with the least possible manual type annotation.

Overview

Nexus was designed with TypeScript in mind. In order to fully typecheck our GraphQL objects, we need to generate a number of types that combine the schema, any type or field configuration provided, and the GraphQL resolution algorithm to create as much type-safety as possible without any additional work importing and assigning types throughout the codebase.

Root Types

A root type is a type representation of the value used to resolve the fields of an object type. It is the object that will be passed as the first argument of resolve. It can be a plain JS object, a database model, a mongoose document, a JS class, anything that fulfills the contract defined by the GraphQL object type, based on the field definitions.

Scalars can also have backing types, representing the value they are parsed into.

Sometimes GraphQL types are passthrough, and don't have a dedicated type backing them. One such case would be in the Edge of a Relay style pagination. In this case, Nexus will generate a type-definition which makes assumptions of the necessary value to fulfill the contract. If this is incorrect, you can always provide a concrete type for the object.

Field Type

A field type is the valid return value used to a field on an object type. In GraphQL, promises can be returned at every level of the type resolution, so we wrap the types in a MaybePromiseDeep<T> type to express this.

Configuring our types

The Ghost Example is the best to look at for an example of how we're able to capture the types from existing runtime objects or definitions and merge them with our schema.

The makeSchema takes several options which helps us find the types we need to import into our generated schema, and customize where these generated types are output. Read more about the API here.

Was this helpful?

Edit this page on Github