Skip to content

docs: type generation for graphql servers #4376

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: 16.x.x
Choose a base branch
from
Open

docs: type generation for graphql servers #4376

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b3b489f
add guide for graphQL server type generation
sarahxsanders Apr 22, 2025
e157546
feedback
sarahxsanders Apr 26, 2025
d0cdf3a
fix spellcheck
sarahxsanders May 13, 2025
9450057
Merge branch '16.x.x' into type-generation
sarahxsanders May 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cspell.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ overrides:
- swcrc
- noreferrer
- xlink
- codegen
- composability
- deduplication

Expand Down
5 changes: 5 additions & 0 deletions website/pages/docs/_meta.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,18 @@ const meta = {
'constructing-types': '',
'oneof-input-objects': '',
'defer-stream': '',
'type-generation': '',
'cursor-based-pagination': '',
'custom-scalars': '',
'advanced-custom-scalars': '',
'n1-dataloader': '',
'resolver-anatomy': '',
'graphql-errors': '',
'-- 3': {
type: 'separator',
title: 'Testing',
},
'-- 4': {
type: 'separator',
title: 'FAQ',
},
Expand Down
208 changes: 208 additions & 0 deletions website/pages/docs/type-generation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,208 @@
---
title: Type Generation for GraphQL
sidebarTitle: Type Generation
---

# Type Generation for GraphQL

Writing a GraphQL server in JavaScript or TypeScript often involves managing complex
types. As your API grows, keeping these types accurate and aligned with your schema
becomes increasingly difficult.

Type generation tools automate this process. Instead of manually defining or maintaining
TypeScript types for your schema and operations, these tools can generate them for you.
This improves safety, reduces bugs, and makes development easier to scale.

This guide walks through common type generation workflows for projects using
`graphql-js`, including when and how to use them effectively.

## Why use type generation?

Type generation improves reliability and developer experience across the development
lifecycle. It's especially valuable when:

- You want strong type safety across your server logic
- Your schema is defined separately in SDL files
- Your API surface is large, rapidly evolving, or used by multiple teams
- You rely on TypeScript for editor tooling, autocomplete, or static analysis

By generating types directly from your schema, you can avoid drift between schema
definitions and implementation logic.

## Code-first development

In a code-first workflow, the schema is constructed entirely in JavaScript or TypeScript
using `graphql-js` constructors like `GraphQLObjectType`, `GraphQLSchema`, and others.
This approach is flexible and lets you build your schema programmatically using native
language features.

If you're using this approach with TypeScript, you already get some built-in type safety
with the types exposed by `graphql-js`. For example, TypeScript can help ensure your resolver
functions return values that match their expected shapes.

However, code-first development has tradeoffs:

- You won't get automatic type definitions for your resolvers unless you generate
them manually or infer them through wrappers.
- Schema documentation, testing, and tool compatibility may require you to export
the schema to SDL first.

You can still use type generation tools like GraphQL Code Generator in a code-first setup.
You just need to convert your schema into SDL.

To export your schema:

```ts
import { printSchema } from 'graphql';
import { schema } from './schema';
import { writeFileSync } from 'fs';

writeFileSync('./schema.graphql', printSchema(schema));
```

Once you've written the SDL, you can treat the project like a schema-first project
for type generation.

## Schema-first development

In a schema-first workflow, your GraphQL schema is written in SDL, for example, `.graphql`
or `.gql` files. This serves as the source of truth for your server. This approach
emphasizes clarity because your schema is defined independently from your business logic.

Schema-first development pairs well with type generation because the schema is
serializable and can be directly used by tools like [GraphQL Code Generator](https://the-guild.dev/graphql/codegen).

With a schema-first workflow, you can:

- Generate resolver type definitions that match your schema
- Generate operation types for client queries, integration tests, or internal tooling
- Detect breaking changes and unused types through schema diffing tools

## Generating resolver types

We recommend using the [GraphQL Code Generator Server Preset](https://the-guild.dev/graphql/codegen/docs/guides/graphql-server-apollo-yoga-with-server-preset)
to generate resolver types. It automatically generates resolver types based on your schema, including parent types,
arguments, return values, and context, without needing extra plugin setup.

Example `codegen.ts` config:

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

const config: CodegenConfig = {
schema: './schema.graphql',
generates: {
'./src/generated/resolvers-types.ts': {
plugins: ['typescript', 'typescript-resolvers'],
},
},
};
export default config;
```

To run the generator:

```bash
npx graphql-codegen
```

This creates a set of resolver types like:

```ts
export type QueryResolvers<ContextType = any> = {
user?: Resolver<User, any, ContextType, RequireFields<QueryUserArgs, 'id'>>;
};
```

These types ensure that the `user` resolver expects an `id` argument and returns a
`User`, giving you confidence and autocomplete while implementing your server logic.

## Using generated types in your server

Once generated, you can use these types directly in your resolver map:

```ts
import { QueryResolvers } from './generated/resolvers-types';

export const queryResolvers: QueryResolvers = {
user: (parent, args, context) => {
return context.db.getUser(args.id);
},
};
```

You can also extract shared `ContextType` and `Resolver`
utility types from the generated file and apply them across your codebase.

## Generating operation types

In addition to resolver types, you can generate types for GraphQL operations such
as queries, mutations, and fragments. This is especially useful for shared integration tests
or client logic that needs to match the schema precisely.

We recommend using the GraphQL Code Generator Server Preset for generating operation types.
The server preset generates both resolver and operation types, without needing to install
or configure additional plugins.

Suppose you have a query in `./src/operations/getUser.graphql`:

```graphql
query GetUser($id: ID!) {
user(id: $id) {
id
name
}
}
```

Update your codegen config:

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

const config: CodegenConfig = {
schema: './schema.graphql',
documents: './src/operations/**/*.graphql',
generates: {
'./src/generated/': {
preset: 'graphql-codegen-preset-server',
},
},
};
export default config;
```

This produces types like `GetUserQuery` and `GetUserQueryVariables`, which you can
import into your client code or test files.

## Typing resolvers manually

If you aren't ready to introduce type generation, you can still get partial type safety
using `graphql-js` built-in types.

```ts
import { GraphQLFieldResolver } from 'graphql';

const myResolver: GraphQLFieldResolver<MyParent, MyContext> = (
parent,
args,
context,
info
) => {
// ...
};
```

This pattern may be enough for small projects or static schemas, but it
can be hard to maintain and scale without automation.
Comment on lines +75 to +197
Copy link

@eddeee888 eddeee888 May 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
With a schema-first workflow, you can:
- Generate resolver type definitions that match your schema
- Generate operation types for client queries, integration tests, or internal tooling
- Detect breaking changes and unused types through schema diffing tools
## Generating resolver types
We recommend using the [GraphQL Code Generator Server Preset](https://the-guild.dev/graphql/codegen/docs/guides/graphql-server-apollo-yoga-with-server-preset)
to generate resolver types. It automatically generates resolver types based on your schema, including parent types,
arguments, return values, and context, without needing extra plugin setup.
Example `codegen.ts` config:
```ts
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
schema: './schema.graphql',
generates: {
'./src/generated/resolvers-types.ts': {
plugins: ['typescript', 'typescript-resolvers'],
},
},
};
export default config;
```
To run the generator:
```bash
npx graphql-codegen
```
This creates a set of resolver types like:
```ts
export type QueryResolvers<ContextType = any> = {
user?: Resolver<User, any, ContextType, RequireFields<QueryUserArgs, 'id'>>;
};
```
These types ensure that the `user` resolver expects an `id` argument and returns a
`User`, giving you confidence and autocomplete while implementing your server logic.
## Using generated types in your server
Once generated, you can use these types directly in your resolver map:
```ts
import { QueryResolvers } from './generated/resolvers-types';
export const queryResolvers: QueryResolvers = {
user: (parent, args, context) => {
return context.db.getUser(args.id);
},
};
```
You can also extract shared `ContextType` and `Resolver`
utility types from the generated file and apply them across your codebase.
## Generating operation types
In addition to resolver types, you can generate types for GraphQL operations such
as queries, mutations, and fragments. This is especially useful for shared integration tests
or client logic that needs to match the schema precisely.
We recommend using the GraphQL Code Generator Server Preset for generating operation types.
The server preset generates both resolver and operation types, without needing to install
or configure additional plugins.
Suppose you have a query in `./src/operations/getUser.graphql`:
```graphql
query GetUser($id: ID!) {
user(id: $id) {
id
name
}
}
```
Update your codegen config:
```ts
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
schema: './schema.graphql',
documents: './src/operations/**/*.graphql',
generates: {
'./src/generated/': {
preset: 'graphql-codegen-preset-server',
},
},
};
export default config;
```
This produces types like `GetUserQuery` and `GetUserQueryVariables`, which you can
import into your client code or test files.
## Typing resolvers manually
If you aren't ready to introduce type generation, you can still get partial type safety
using `graphql-js` built-in types.
```ts
import { GraphQLFieldResolver } from 'graphql';
const myResolver: GraphQLFieldResolver<MyParent, MyContext> = (
parent,
args,
context,
info
) => {
// ...
};
```
This pattern may be enough for small projects or static schemas, but it
can be hard to maintain and scale without automation.
With a schema-first workflow, you can:
- Generate resolver type definitions and files that match your schema
- Generate operation types for client queries, integration tests, or internal tooling
- Detect breaking changes and unused types through schema diffing tools
## Generating resolver types
We recommend using the [Server Preset](https://www.npmjs.com/package/@eddeee888/gcg-typescript-resolver-files) for a managed workflow. It automatically generates types and files based on your schema without needing extra plugin setup:
- resolver types, including parent types, arguments, return values, and context.
- resolver files with types wired up, ready for your business logic
- resolver map and type definitions to plug into GraphQL servers
Example codegen config:
```ts filename="codegen.ts"
import type { CodegenConfig } from "@graphql-codegen/cli";
import { defineConfig } from "@eddeee888/gcg-typescript-resolver-files";
const config: CodegenConfig = {
schema: "src/**/schema.graphql",
generates: {
"src/schema": defineConfig({
resolverGeneration: "minimal",
}),
},
};
export default config;

Note: this setup expects your schema is split into modules to improve readability and maintainability:

├── src/
│   ├── schema/
│   │   ├── base/
│   │   │   ├── schema.graphql
│   │   ├── user/
│   │   │   ├── schema.graphql
│   │   ├── book/
│   │   │   ├── schema.graphql

To run the generator:

npx graphql-codegen

This creates resolver files that like:

import type { QueryResolvers } from "./../../../types.generated";
export const user: NonNullable<QueryResolvers["user"]> = async (
  _parent,
  _arg,
  _ctx,
) => {
  /* Implement Query.user resolver logic here */
};

The user query resolver is typed to ensure that the user resolver expects an id argument and returns a
User, giving you confidence and autocomplete while implementing your server logic, which may look like this:

export const user: NonNullable<QueryResolvers["user"]> = async (
  parent,
  args,
  context,
) => {
  return context.db.getUser(args.id);
};

Check out the official Server Preset guide to learn about its other features, including mappers convention and static analysis for runtime safety.

Generating operation types

In addition to resolver types, you can generate types for GraphQL operations such as queries, mutations, and fragments. This is especially useful for shared integration tests or client logic that needs to match the schema precisely.

We recommend using the GraphQL Code Generator Client Preset for a managed workflow:

  • write operations with GraphQL syntax in the same file where it is used
  • get type-safety when using the result

Example codegen config

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

const config: CodegenConfig = {
  schema: "src/**/schema.graphql",
  documents: ["src/**/*.ts"],
  ignoreNoDocuments: true,
  generates: {
    "./src/graphql/": {
      preset: "client",
      config: {
        documentMode: "string",
      },
    },
  },
};

export default config;

Now, run codegen in watch mode:

npx graphql-codegen --config codegen.ts --watch

Now, we can import the graphql function from src/graphql/ to write GraphQL operations directly in your TypeScript files:

import { graphql } from "./graphql";

const UserQuery = graphql(`
  query User($id: ID!) {
    user(id: ID!) {
      id
      fullName
    }
  }
`);

const response = await fetch("https://graphql.org/graphql/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/graphql-response+json",
  },
  body: JSON.stringify({
    query: UserQuery,
    variables: { id: "1" },
  }),
});

if (!response.ok) {
  throw new Error("Network response was not ok");
}

const result: ResultOf<typeof UserQuery> = await response.json();

console.log(result);

Check out Client Preset guides for popular framework and GraphQL clients:


## Best practices for CI and maintenance

To keep your type generation reliable and consistent:

- Check in generated files to version control so teammates and CI systems don't produce
divergent results.
- Run type generation in CI to ensure types stay in sync with schema changes.
- Use schema diffing tools like `graphql-inspector` to catch breaking changes before
they're merged.
- Automate regeneration with pre-commit hooks, GitHub Actions, or lint-staged workflows.
Loading