Graphql Codegen

GraphQL Code Generator Skill

Type-safe GraphQL with automatic code generation

Overview

Learn to use GraphQL Code Generator to automatically generate TypeScript types, React hooks, and more from your GraphQL schema and operations.

---

Quick Reference

---

Setup

1. Installation

npm install -D @graphql-codegen/cli \
  @graphql-codegen/typescript \
  @graphql-codegen/typescript-operations \
  @graphql-codegen/typescript-react-apollo \
  @parcel/watcher

2. Configuration

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

const config: CodegenConfig = {
  // Schema source
  schema: 'http://localhost:4000/graphql',

  // Operations to generate from
  documents: ['src/**/*.graphql', 'src/**/*.tsx'],

  // Output
  generates: {
    './src/generated/graphql.ts': {
      plugins: [
        'typescript',
        'typescript-operations',
        'typescript-react-apollo',
      ],
      config: {
        // Custom scalars
        scalars: {
          DateTime: 'string',
          JSON: 'Record<string, unknown>',
        },
        // Generate hooks
        withHooks: true,
        // Use enums as types
        enumsAsTypes: true,
      },
    },
  },
};

export default config;

3. Scripts

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.ts",
    "codegen:watch": "graphql-codegen --config codegen.ts --watch"
  }
}

---

Usage Examples

1. Define Operations

# src/graphql/queries.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

query GetUsers($first: Int!, $after: String) {
  users(first: $first, after: $after) {
    edges {
      node {
        ...UserFields
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

fragment UserFields on User {
  id
  name
  email
  avatar
}

# src/graphql/mutations.graphql
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      ...UserFields
    }
    errors {
      field
      message
    }
  }
}

2. Use Generated Code

// Types and hooks are generated
import {
  useGetUserQuery,
  useGetUsersQuery,
  useCreateUserMutation,
  UserFieldsFragment,
  GetUserQuery,
} from '../generated/graphql';

// Query with full type safety
function UserProfile({ userId }: { userId: string }) {
  const { data, loading, error } = useGetUserQuery({
    variables: { id: userId }, // Type-checked!
  });

  if (loading) return <Spinner />;
  if (error) return <Error />;

  // data.user is fully typed
  return <div>{data?.user?.name}</div>;
}

// Mutation with type safety
function CreateUser() {
  const [createUser] = useCreateUserMutation({
    update(cache, { data }) {
      // data is typed
      if (data?.createUser.user) {
        // ...
      }
    },
  });

  const handleSubmit = (input: CreateUserInput) => {
    createUser({ variables: { input } }); // Type-checked!
  };
}

// Fragment type
function UserCard({ user }: { user: UserFieldsFragment }) {
  return <div>{user.name}</div>; // Typed fields
}

---

Advanced Config

Multiple Outputs

const config: CodegenConfig = {
  schema: 'http://localhost:4000/graphql',
  documents: 'src/**/*.graphql',

  generates: {
    // Types only
    './src/types.ts': {
      plugins: ['typescript'],
    },

    // Operations with type imports
    './src/operations.ts': {
      preset: 'import-types',
      presetConfig: { typesPath: './types' },
      plugins: ['typescript-operations'],
    },

    // Hooks
    './src/hooks.ts': {
      preset: 'import-types',
      presetConfig: { typesPath: './types' },
      plugins: ['typescript-react-apollo'],
    },

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

Client Preset (Recommended)

const config: CodegenConfig = {
  schema: 'http://localhost:4000/graphql',
  documents: 'src/**/*.tsx',

  generates: {
    './src/gql/': {
      preset: 'client',
      config: {
        fragmentMasking: { unmaskFunctionName: 'getFragmentData' },
      },
    },
  },
};

// Usage
import { gql, getFragmentData } from '../gql';

const UserQuery = gql(`
  query GetUser($id: ID!) {
    user(id: $id) {
      ...UserAvatar
    }
  }
`);

const UserAvatarFragment = gql(`
  fragment UserAvatar on User {
    avatar
  }
`);

function Profile({ userId }) {
  const { data } = useQuery(UserQuery, { variables: { id: userId } });
  const avatar = getFragmentData(UserAvatarFragment, data?.user);
}

---

Troubleshooting

Debug

# Validate schema access
curl http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __schema { types { name } } }"}'

# Verbose codegen
npx graphql-codegen --verbose

# Check config
npx graphql-codegen --check

---

Usage

Skill("graphql-codegen")

Related Skills

• graphql-fundamentals - Schema syntax
• graphql-apollo-client - Using generated hooks
• graphql-schema-design - Better types

Related Agent

• 07-graphql-codegen - For detailed guidance

Graphql Codegen Guide

Overview

This guide provides comprehensive documentation for the graphql-codegen skill in the custom-plugin-graphql plugin.

Category: Api

Quick Start

Prerequisites

• Familiarity with api concepts
• Development environment set up
• Plugin installed and configured

Basic Usage

# Invoke the skill
claude "graphql-codegen - [your task description]"

# Example
claude "graphql-codegen - analyze the current implementation"

Core Concepts

Key Principles

1. Consistency - Follow established patterns 2. Clarity - Write readable, maintainable code 3. Quality - Validate before deployment

Best Practices

• Always validate input data
• Handle edge cases explicitly
• Document your decisions
• Write tests for critical paths

Common Tasks

Task 1: Basic Implementation

# Example implementation pattern
def implement_graphql_codegen(input_data):
    """
    Implement graphql-codegen functionality.

    Args:
        input_data: Input to process

    Returns:
        Processed result
    """
    # Validate input
    if not input_data:
        raise ValueError("Input required")

    # Process
    result = process(input_data)

    # Return
    return result

Task 2: Advanced Usage

For advanced scenarios, consider:

• Configuration customization via assets/config.yaml
• Validation using scripts/validate.py
• Integration with other skills

Troubleshooting

Common Issues

Related Resources

• SKILL.md - Skill specification
• config.yaml - Configuration options
• validate.py - Validation script

---

Last updated: 2025-12-30

Graphql Codegen Patterns

Design Patterns

Pattern 1: Input Validation

Always validate input before processing:

def validate_input(data):
    if data is None:
        raise ValueError("Data cannot be None")
    if not isinstance(data, dict):
        raise TypeError("Data must be a dictionary")
    return True

Pattern 2: Error Handling

Use consistent error handling:

try:
    result = risky_operation()
except SpecificError as e:
    logger.error(f"Operation failed: {e}")
    handle_error(e)
except Exception as e:
    logger.exception("Unexpected error")
    raise

Pattern 3: Configuration Loading

Load and validate configuration:

import yaml

def load_config(config_path):
    with open(config_path) as f:
        config = yaml.safe_load(f)
    validate_config(config)
    return config

Anti-Patterns to Avoid

❌ Don't: Swallow Exceptions

# BAD
try:
    do_something()
except:
    pass

✅ Do: Handle Explicitly

# GOOD
try:
    do_something()
except SpecificError as e:
    logger.warning(f"Expected error: {e}")
    return default_value

Category-Specific Patterns: Api

Recommended Approach

1. Start with the simplest implementation 2. Add complexity only when needed 3. Test each addition 4. Document decisions

Common Integration Points

• Configuration: assets/config.yaml
• Validation: scripts/validate.py
• Documentation: references/GUIDE.md

---

Pattern library for graphql-codegen skill