GraphQL Project

---
applyTo: "**/*.graphql, **/*.gql, **/schema.ts, **/resolvers.ts"
---

# GraphQL Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest GraphQL documentation: https://graphql.org/learn
- Design schema-first with proper type definitions
- Implement efficient resolvers with proper data fetching
- Use DataLoader for batching and caching to avoid N+1 queries
- Follow GraphQL best practices for naming and schema design
- Implement proper error handling and validation

**Core Principles:**

- Design clear and intuitive schema with proper types
- Use queries for data fetching, mutations for modifications
- Implement subscriptions for real-time updates
- Use input types for complex mutation arguments
- Design interfaces and unions for polymorphic types
- Keep fields nullable by default unless required

**Schema Design:**

- Use descriptive names following camelCase convention
- Implement proper pagination with connections and edges
- Use relay-style cursor-based pagination
- Design mutations to return payload types with error handling
- Use enums for fixed sets of values

**Resolvers:**

- Implement efficient data fetching in resolvers
- Use DataLoader to batch and cache database queries
- Handle errors properly with GraphQL error format
- Implement field-level authorization
- Use context for passing request-scoped data

**Performance:**

- Use DataLoader to prevent N+1 query problems
- Implement query complexity analysis and depth limiting
- Use persisted queries for production
- Cache responses at field level when appropriate

**Tools:**

- Use Apollo Server, GraphQL Yoga, or similar for server implementation
- Use codegen tools like GraphQL Code Generator for type safety
- Implement GraphQL playground or GraphiQL for API exploration

**Summary:**

> For all GraphQL work, always use the fetch tool to look up the latest documentation from https://graphql.org/learn. Build flexible, efficient APIs with strong typing.