GraphQL Code Generator Pattern

Generate type-safe TypeScript code from GraphQL schemas and operations to eliminate manual type maintenance

When to Use

• Starting a new GraphQL project with TypeScript
• Adding type safety to existing GraphQL queries and mutations
• Generating typed React hooks for Apollo Client or urql
• Generating resolver type signatures for the server
• Keeping TypeScript types in sync with schema changes

Instructions

1. Install the codegen CLI and core plugins.

npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-resolvers

2. Create a

   codegen.ts

   configuration file at the project root. Use the TypeScript config format for type-safe configuration.

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

const config: CodegenConfig = {
  schema: 'src/schema/**/*.graphql',
  documents: 'src/**/*.{ts,tsx}',
  generates: {
    'src/__generated__/types.ts': {
      plugins: ['typescript', 'typescript-operations'],
      config: {
        strictScalars: true,
        scalars: {
          DateTime: 'string',
          JSON: 'Record<string, unknown>',
        },
      },
    },
    'src/__generated__/resolvers.ts': {
      plugins: ['typescript', 'typescript-resolvers'],
      config: {
        useIndexSignature: true,
        contextType: '../context#Context',
      },
    },
  },
};

export default config;

3. Use

   TypedDocumentNode

   for end-to-end type safety. This plugin generates typed document nodes that carry their variables and result types — Apollo Client and urql pick them up automatically.

// codegen generates:
// export const GetUserDocument: TypedDocumentNode<GetUserQuery, GetUserQueryVariables>

// Usage — variables and data are fully typed with no extra annotations:
const { data } = useQuery(GetUserDocument, { variables: { id: '1' } });
// data.user.name is typed as string

4. Generate typed React hooks for client-side usage. Add the

   typescript-react-apollo

   or

   typescript-urql

   plugin to generate

   useGetUserQuery()

   hooks directly.

// codegen.ts addition
'src/__generated__/hooks.ts': {
  plugins: ['typescript', 'typescript-operations', 'typescript-react-apollo'],
  config: {
    withHooks: true,
    withComponent: false,
  },
},

5. Use

   near-operation-file

   preset to co-locate generated types next to the files that define the operations, instead of one giant generated file.

generates: {
  'src/': {
    preset: 'near-operation-file',
    presetConfig: { extension: '.generated.ts', baseTypesPath: '__generated__/types.ts' },
    plugins: ['typescript-operations', 'typescript-react-apollo'],
  },
},

6. Run codegen in watch mode during development and as a CI check to ensure types are up to date.

{
  "scripts": {
    "codegen": "graphql-codegen",
    "codegen:watch": "graphql-codegen --watch"
  }
}

7. Enable

   strictScalars

   to force explicit scalar mappings. Without this, custom scalars default to

   any

   , defeating the purpose of code generation.

8. Type your resolvers with the generated

   Resolvers

   type. This catches mismatches between your schema and resolver implementations at compile time.

import { Resolvers } from './__generated__/resolvers';

export const resolvers: Resolvers = {
  Query: {
    user: async (_parent, { id }, context) => {
      // args.id is typed as string, return type is enforced
      return context.dataSources.users.findById(id);
    },
  },
};

9. Add generated files to

   .gitignore

   or commit them — pick one strategy and enforce it. Committing ensures CI does not need the schema endpoint; ignoring ensures no stale generated code.

Details

Plugin ecosystem:

typescript

(base types from schema),

typescript-operations

(types from queries/mutations),

typescript-resolvers

(resolver signatures),

typescript-react-apollo

/

typescript-urql

(framework hooks),

typed-document-node

(framework-agnostic typed documents).

Schema sources: Codegen can read schemas from

.graphql

files, a running endpoint, a JSON introspection result, or code-first builders. Prefer

.graphql

files for CI stability.

Fragment handling: Codegen generates types for fragments and composes them into operation types. Use fragments for shared fields to keep generated types DRY.

Enum handling: By default, codegen generates TypeScript

enum

. Set

enumsAsTypes: true

to generate union string literals instead, which work better with tree-shaking and are simpler to use.

Common mistakes:

• Forgetting to re-run codegen after schema changes (use watch mode or CI check)
• Not mapping custom scalars, resulting in

  any

  types leaking through
• Generating into

  node_modules

  or build output (generate into

  src/

  )
• Mixing hand-written and generated types for the same schema entity

Source

https://the-guild.dev/graphql/codegen

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.