Claude Skills Guide

Claude Code for GraphQL Codegen Workflow Tutorial

If you’re working with GraphQL in a modern TypeScript project, you’ve probably experienced the tedium of manually keeping your API types in sync with your schema. GraphQL Codegen solves this problem by automatically generating types from your schema, but setting up and maintaining the workflow can still be time-consuming. This is where Claude Code becomes your secret weapon.

In this tutorial, I’ll show you how to use Claude Code to automate your GraphQL codegen workflow, making type generation seamless and almost entirely hands-off.

Scope of this tutorial: This article focuses specifically on automating the graphql-codegen CLI tool—configuring codegen.yml, running codegen commands, watch mode, pre-commit validation, and troubleshooting codegen errors. If you want to generate server-side GraphQL schema artifacts and resolver scaffolding from TypeScript models, see the GraphQL Code Generation Workflow guide. If you need client-side type and hook generation for React/Apollo, see the GraphQL Client Codegen Guide.

What is GraphQL Codegen?

GraphQL Code Generator is a tool that reads your GraphQL schema and operations, then generates type-safe code for your frontend or backend. Instead of manually defining types like this:

interface User {
  id: string;
  name: string;
  email: string;
  posts: Post[];
}

You let Codegen handle it automatically, ensuring your types always match your schema.

Setting Up Your Claude Code Project

First, ensure you have Claude Code installed and configured. If you haven’t already, install it and set up your project:

npm install -g @anthropic-ai/claude-code
mkdir my-graphql-project && cd my-graphql-project
mkdir -p .claude

Now let’s set up GraphQL Codegen in your project:

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

Create your codegen configuration file:

# codegen.yml
overwrite: true
schema: "./schema.graphql"
documents: "./src/**/*.graphql"
generates:
  src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
  ./src/generated/introspection.json:
    plugins:
      - introspection

Automating with Claude Code

Here’s where Claude Code shines. Instead of manually running codegen commands, you can create Claude Code prompts that handle the entire workflow.

Creating Your Codegen Agent

Create a file called .claude/codegen-agent.md in your project:

# GraphQL Codegen Agent

You are responsible for maintaining the GraphQL codegen workflow. Your responsibilities:

1. Run codegen when schema changes are detected
2. Validate generated types compile correctly
3. Report any codegen errors
4. Keep the codegen configuration updated

Always run `graphql-codegen` after any schema modifications.

Integrating with Claude Code

Now you can invoke Claude Code to handle codegen:

claude --print "Run graphql-codegen and verify the generated types compile"

Or create a custom script in your package.json:

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.yml",
    "codegen:watch": "graphql-codegen --config codegen.yml --watch",
    "codegen:check": "graphql-codegen --config codegen.yml && tsc --noEmit"
  }
}

Advanced Workflow Patterns

Automatic Schema Sync

Set up Claude Code to automatically sync your schema from your API:

// scripts/sync-schema.ts
import { GraphQLClient, gql } from 'graphql-request';
import { writeFileSync } from 'fs';

const client = new GraphQLClient(process.env.GRAPHQL_ENDPOINT);

async function fetchSchema() {
  const query = gql`
    query IntrospectionQuery {
      __schema {
        types {
          ...FullType
        }
      }
    }
    fragment FullType on __Type {
      kind
      name
      fields(includeDeprecated: true) {
        name
        args {
          ...InputValue
        }
        type {
          ...TypeRef
        }
        isDeprecated
        deprecationReason
      }
      inputFields {
        ...InputValue
      }
      interfaces {
        ...TypeRef
      }
      enumValues(includeDeprecated: true) {
        name
        isDeprecated
        deprecationReason
      }
      possibleTypes {
        ...TypeRef
      }
    }
    fragment InputValue on __InputValue {
      name
      type {
        ...TypeRef
      }
      defaultValue
    }
    fragment TypeRef on __Type {
      kind
      name
      ofType {
        kind
        name
        ofType {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
              ofType {
                kind
                name
                ofType {
                  kind
                  name
                  ofType {
                    kind
                  }
                }
              }
            }
          }
        }
      }
    }
  `;
  
  const schema = await client.request(query);
  writeFileSync('./schema.graphql', printSchema(schema));
}

Watching for Changes

Use Claude Code’s file watching capabilities to trigger codegen automatically:

# .claude/watch-config.yml
watch:
  - path: ./schema.graphql
    action: run-codegen
  - path: ./src/**/*.graphql
    action: run-codegen

actions:
  run-codegen:
    command: npm run codegen
    notify: true

Best Practices

1. Use Fragment Matching

Configure fragment matching to avoid type conflicts:

generates:
  src/generated/graphql.ts:
    plugins:
      - typescript
    config:
      withHooks: true
      withComponent: false
      withHOC: false
      avoidOptionals: true
      strict: true

2. Implement Pre-Commit Validation

Add a pre-commit hook to ensure codegen runs successfully:

{
  "husky": {
    "hooks": {
      "pre-commit": "npm run codegen:check"
    }
  }
}

3. Organize Your Operations

Keep your GraphQL operations well-organized:

src/
  graphql/
    queries/
      users.graphql
      posts.graphql
    mutations/
      create-user.graphql
    fragments/
      user-fields.graphql
  generated/
    graphql.ts

Troubleshooting Common Issues

Schema Parse Errors

If you encounter schema parsing errors, ensure your schema file is valid:

graphql-codegen --config codegen.yml --verbose

Type Mismatches

When generated types don’t match your expectations, check your operation definitions and ensure they use proper fragment spreads.

Watch Mode Issues

For watch mode problems, ensure you’re using the correct file paths in your configuration and that your TypeScript project is properly configured.

Conclusion

Claude Code transforms GraphQL codegen from a manual, error-prone process into an automated, reliable workflow. By integrating codegen with Claude Code’s capabilities, you get:

Start implementing this workflow in your project today, and you’ll wonder how you ever managed without it.

Remember to regularly update your Claude Code agents as your project evolves, and keep your codegen configuration in version control to ensure consistency across your team.

Built by theluckystrike — More at zovo.one

Explore Our Developer Guides

© 2026 theluckystrike Developer Guides