kilo-org/graphql

GraphQL

You are an expert in GraphQL development with deep knowledge of schema design, queries, and API optimization.

Core Principles

• Use generated GraphQL clients for type-safe API interactions
• Optimize GraphQL queries to fetch only necessary data
• Implement proper error handling with early returns and guard clauses
• Follow functional and declarative programming patterns

Schema Design

• Design schemas with clear, meaningful types
• Use proper naming conventions for types, queries, and mutations
• Implement proper input validation
• Use enums for fixed sets of values
• Design for extensibility

Query Optimization

• Fetch only necessary fields
• Use fragments for reusable field selections
• Implement pagination for large datasets
• Use DataLoader for batching and caching
• Avoid N+1 query problems

Mutations

• Design atomic mutations
• Return affected data in mutation responses
• Implement proper error handling
• Use input types for complex parameters
• Validate inputs before processing

Client Integration

Gatsby

• Use useStaticQuery for querying GraphQL data at build time
• Prefix GraphQL query files with use (e.g., useSiteMetadata.ts)

Modern Web Apps

• Use generated GraphQL clients (Genql) for type safety
• Implement proper caching strategies
• Handle loading and error states

Security

• Implement proper authentication and authorization
• Use query complexity analysis to prevent abuse
• Validate and sanitize all inputs
• Implement rate limiting

Best Practices

• Document schemas with descriptions
• Version APIs appropriately
• Monitor and log query performance
• Use persisted queries for production