Generating client types

Pothos does not have a built in mechanism for generating types to use with a client, but graphql-code-generator can be configured to consume a schema directly from your typescript files.

Export your schema

The first thing you will need is a file that exports your built schema. The schema should be exported as schema or as the default export. This will be used to generate your client types, but can also be the schema you use in your server.

// schema.ts

// Import the builder
import builder from './builder';

// Import your type definitions
import './types/Query';
import './types/User';
import './types/Posts';

// Build and export the schema
export const schema = builder.toSchema();

Setting up graphql-code-generator

There are many different ways to set up graphql-code-generator, and the details depend a lot on your needs.

See the graphql-code-generator documentation for more details.

Install the codegen packages

npm install --save graphql
npm install --save -D typescript @graphql-codegen/cli @graphql-codegen/client-preset

Configure the codegen to import your schema

Create a codegen.ts file in the root of your project:

import type { CodegenConfig } from '@graphql-codegen/cli';
import { printSchema } from 'graphql';
import { schema } from './src/schema';

const config: CodegenConfig = {
  schema: printSchema(schema),
  documents: ['src/**/*.{graphql,ts,tsx}', '!src/gql/**'],
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: [],
    },
  },
};

export default config;

You can customize this config as needed, but the relevant parts are:

• Importing your GraphQL schema, this should be the result of calling builder.toSchema({})
• using printSchema from graphql to convert the schema to a string

Run generation

The documents pattern must match your client queries, mutations, and fragments. Adjust it for your project and exclude the generated directory. For example, a file named src/queries.graphql can contain a named query that selects fields from your schema.

npx graphql-codegen --config codegen.ts

Run this again when your schema or operations change. The client preset generates typed operation documents and helpers in src/gql/; the result types reflect the fields each operation selects. The CLI imports your schema module, so its environment variables and other runtime dependencies must be available. Keep server startup outside that module.

Generating a schema.graphql file with graphql-code-generator

You can generate a schema.graphql file with graphql-code-generator by adding the schema-ast plugin:

npm install --save -D @graphql-codegen/schema-ast

// codegen.ts
import { printSchema } from 'graphql';
import type { CodegenConfig } from '@graphql-codegen/cli';
import { schema } from './src/schema';

const config: CodegenConfig = {
  schema: printSchema(schema),
  documents: ['src/**/*.{graphql,ts,tsx}', '!src/gql/**'],
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: [],
    },
    'schema.graphql': {
      plugins: ['schema-ast'],
    },
  },
};

export default config;

Adding scalars

Configure custom scalars to match their serialized values on the client. Add the following config property to the configuration above:

config: {
  strictScalars: true,
  scalars: {
    UUID: 'string',
    DateTime: 'string',
  },
},

A DateTime scalar commonly serializes to an ISO date string. Mapping it to Date changes only the TypeScript type; Codegen does not convert JSON strings into JavaScript Date instances. Use Date only if your client actually performs that conversion. strictScalars makes generation fail when a custom scalar has no mapping; see the client preset configuration.

Alternatives

In some cases you may want to use an alternative method for loading your schema.

Printing the schema to a file

You can use the printSchema function from graphql to print your schema to a file, see Printing Schemas for more details:

By writing the schema to a file, you will be able to load the schema from a file instead of importing it each time you want to generate your schema.

Having your schema written to a file, and checked into source control has many benefits, like easier code reviews, and better interoperability with other schema dependent graphql tools, so setting this up is worthwhile even if you do not need it for generating client types:

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: './path/to/schema.graphql',
  documents: ['src/**/*.{graphql,ts,tsx}', '!src/gql/**'],
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: [],
    },
  },
};

export default config;

Using introspection from your dev (or production) server

Rather than using a schema SDL file, graphql-code-generator can also use introspection to load your schema. To do this, you will need to ensure that your server has introspection enabled and that Codegen can authenticate if the endpoint requires it. Introspection defaults depend on the server and its configuration.

You can then configure graphql-code-generator to use introspection by passing the URL to your graphql endpoint:

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'http://localhost:3000/graphql',
  documents: ['src/**/*.{graphql,ts,tsx}', '!src/gql/**'],
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: [],
    },
  },
};

export default config;