GraphQL Operations Developer

Overview

Guide the creation and maintenance of GraphQL operations following project conventions for type safety, organization, error handling, and testing with gql.tada and urql.

When to Use

• Creating new GraphQL queries or mutations
• Integrating with Saleor API endpoints
• Updating schema after Saleor changes
• Working with urql client configuration
• Creating MSW mocks for testing

Quick Reference

File Organization

src/lib/graphql/
├── client.ts              # urql client configuration
├── operations/            # GraphQL operation definitions
├── fragments/             # Reusable GraphQL fragments
├── __mocks__/             # MSW test mocks
└── schema.graphql         # Saleor schema (generated)

src/modules/<entity>/
├── repository.ts          # Uses GraphQL operations
└── ...

Creating Operations

Use gql.tada for all operations. Types are inferred from schema automatically:

import { graphql } from 'gql.tada';

export const GetCategoriesQuery = graphql(`
  query GetCategories($first: Int!) {
    categories(first: $first) {
      edges {
        node { id, name, slug, description }
      }
    }
  }
`);

// Type inferred automatically
type GetCategoriesResult = ResultOf<typeof GetCategoriesQuery>;

For shared fields, extract fragments and pass as second argument to graphql().

Repository Pattern

Each entity has a repository class that encapsulates GraphQL operations and maps responses to domain models:

export class CategoryRepository {
  constructor(private readonly client: Client) {}

  async findAll(): Promise<Category[]> {
    const result = await this.client.query(GetCategoriesQuery, { first: 100 });
    if (result.error) {
      throw GraphQLError.fromCombinedError(result.error, 'GetCategories');
    }
    return this.mapCategories(result.data?.categories);
  }

  async create(input: CategoryInput): Promise<Category> {
    const result = await this.client.mutation(CreateCategoryMutation, { input });
    if (result.error) {
      throw GraphQLError.fromCombinedError(result.error, 'CreateCategory');
    }
    if (result.data?.categoryCreate?.errors?.length) {
      throw new GraphQLError('Category creation failed', result.data.categoryCreate.errors);
    }
    return this.mapCategory(result.data?.categoryCreate?.category);
  }
}

Key pattern: Always map GraphQL responses to domain models in the repository. Never expose GraphQL types to services.

Error Handling

Two error types to always check:

1. Network/GraphQL errors (result.error): Wrap with GraphQLError.fromCombinedError(error, 'OperationName', { context })
2. Mutation validation errors (result.data?.mutation?.errors): Check array length, throw with field details

See [references/error-handling.md](references/error-handling.md) for complete error patterns, classification, and MSW error mocking.

Schema Management

pnpm fetch-schema  # Updates schema.graphql and graphql-env.d.ts

Update schema when: new Saleor features needed, after Saleor version upgrade, or when encountering schema drift errors. Always commit schema changes with the feature implementation.

Testing

Mock GraphQL operations with MSW using graphql.query() and graphql.mutation() handlers. See analyzing-test-coverage skill for full MSW setup patterns.

Client Configuration

The urql client is configured in src/lib/graphql/client.ts with: cacheExchange, authExchange (Bearer token), retryExchange (1s-15s backoff, 5 attempts, retries on 429 and network errors), and fetchExchange.

Best Practices

Do:

• Use gql.tada for all operations (automatic type inference)
• Keep operations close to their domain modules
• Map GraphQL responses to domain models in repository
• Include operation name in error context
• Update mocks when schema changes
• Extract shared fields to fragments

Don't:

• Use raw string queries (no type safety)
• Expose GraphQL types directly to services
• Skip error handling for any operation
• Hardcode pagination limits (use constants)

Validation Checkpoints

Common Mistakes

External Documentation

For up-to-date library docs, use Context7 MCP:

• urql: resolve-library-id with /urql-graphql/urql
• gql.tada: resolve-library-id with "gql.tada"

References

Skill Reference Files

• [Error Handling](references/error-handling.md) - Error types, wrapping, classification, and MSW error mocking
• [Fragment Patterns](references/fragment-patterns.md) - Fragment composition and type inference

Project Resources

• src/lib/graphql/client.ts - Client configuration
• src/lib/graphql/operations/ - Existing operations
• docs/CODE_QUALITY.md#graphql--external-integrations - Quality standards

Related Skills

• Complete entity workflow: See adding-entity-types for full implementation including bulk mutations
• Bulk operations: See adding-entity-types/references/bulk-mutations.md for chunking patterns
• Testing GraphQL: See analyzing-test-coverage for MSW setup

Troubleshooting

Common Error Scenarios

Debugging Steps

1. Check schema freshness: pnpm fetch-schema — ensures local schema matches remote
2. Isolate the operation: Test the query/mutation in Saleor's GraphQL Playground first
3. Add error context: Include operation name in all error wrapping calls
4. Check MSW handlers: Ensure test mocks match updated operation signatures
5. Verify type inference: Hover over ResultOf<typeof Query> in IDE to confirm types

Quick Reference Rule

For a condensed quick reference, see .claude/rules/graphql-patterns.md (automatically loaded when editing GraphQL operations and repository files).