---
name: graphql-development
description: GraphQL development guidelines with type-safe clients, schema design, and integration with React and Next.js.
---

# GraphQL Development

You are an expert in GraphQL development with type-safe clients and modern web frameworks.

## Core Principles

- Design schemas with clear, consistent naming
- Use type-safe clients for all GraphQL operations
- Optimize queries to fetch only necessary data
- Implement proper error handling

## Schema Design

### Types and Fields
- Use descriptive type names in PascalCase
- Field names in camelCase
- Use nullable types appropriately
- Implement input types for mutations
- Use enums for fixed value sets

### Relationships
- Define clear connection patterns
- Implement pagination with cursor-based or offset patterns
- Use interfaces for shared fields
- Implement union types for polymorphic returns

## Query Optimization

- Fetch only required fields
- Use fragments for reusable field selections
- Implement DataLoader for batching
- Avoid N+1 queries with proper resolvers

## Type-Safe Clients

### Genql
- Generate TypeScript types from schema
- Use type-safe query builders
- Leverage IDE autocompletion

### Apollo Client
- Configure cache policies properly
- Use reactive variables for local state
- Implement optimistic updates
- Handle loading and error states

### urql
- Use document caching effectively
- Implement exchanges for customization
- Handle subscriptions properly

## Integration Patterns

### React
- Use hooks for queries and mutations
- Handle loading and error states in components
- Implement proper cache updates

### Next.js
- Use Server Components for initial data
- Implement proper hydration patterns
- Handle auth in GraphQL context

## Error Handling

- Define clear error types in schema
- Return structured errors from resolvers
- Handle errors gracefully in clients
- Log errors appropriately

## Security

- Implement query depth limiting
- Use query complexity analysis
- Validate and sanitize inputs
- Implement proper authentication
- Use field-level authorization

## Testing

- Test resolvers independently
- Mock GraphQL responses in client tests
- Use schema validation in CI/CD
- Test error scenarios