graphql

---
description: This rule provides comprehensive best practices and coding standards for GraphQL development, covering code organization, performance, security, testing, and common pitfalls.
globs: **/*.graphql
---

- **Naming Conventions**:
  - Use `camelCase` for field names, argument names, and directive names. This is a widely accepted convention that enhances readability and consistency.
  - Use the suffix `Input` when naming input types (e.g., `UserInput`). This clearly distinguishes input types from other types in your schema.
  - Avoid verb prefixes like `get` in field names (e.g., use `users` instead of `getUsers`). This maintains clarity and consistency in your schema.

- **Schema Design and Query Optimization**:
  - Design your schema to prevent over-fetching or under-fetching of data. Use fragments to request only the necessary data.
  - Use variables for parameters instead of hard-coded values. This enhances flexibility and maintainability, and allows for query caching.
  - Implement pagination for large datasets to avoid overwhelming the client and improve performance.
  - Use field aliases to rename fields in the response, which can be useful for backward compatibility or to simplify the client-side code.

- **Code Organization and Structure**:
  - **Directory Structure**: Organize your GraphQL schema files into a logical directory structure.  Consider grouping related types and resolvers together (e.g., `schemas/user/`, `resolvers/user/`).
  - **File Naming Conventions**: Use descriptive names for schema files (e.g., `user.graphql`, `product.graphql`).
  - **Module Organization**:  Break down your schema into smaller, reusable modules. Use schema stitching or federation to combine these modules into a single API.
  - **Component Architecture**: If using a GraphQL client library like Apollo Client or Relay, structure your components to efficiently manage GraphQL queries and data fetching.

- **Common Patterns and Anti-patterns**:
  - **Design Patterns**: Consider using patterns like the Facade pattern to simplify complex resolvers or the DataLoader pattern to batch and cache data fetching.
  - **Anti-patterns**: Avoid creating overly complex queries that fetch too much data in a single request.  Also avoid using deeply nested resolvers, as this can lead to performance issues.
  - **State Management**:  Choose a state management solution that integrates well with your GraphQL client library.  Consider using Apollo Client's cache or Relay's store for client-side data management.
  - **Error Handling**: Implement robust error handling in your resolvers.  Return user-friendly error messages and log detailed error information on the server.

- **Performance Considerations**:
  - **Optimization Techniques**: Use techniques like query batching, caching, and persisted queries to optimize performance.
  - **Memory Management**: Be mindful of memory usage in your resolvers, especially when dealing with large datasets.
  - **Lazy Loading**: Implement lazy loading for non-critical data to improve initial page load times.

- **Security Best Practices**:
  - **Input Validation**: Validate all user inputs to prevent injection attacks and other security vulnerabilities. Use appropriate data types and constraints in your schema.
  - **Authentication and Authorization**: Implement strong authentication and authorization mechanisms to protect your API. Use role-based access control (RBAC) to restrict access to sensitive data.
  - **Data Protection**: Protect sensitive data by encrypting it at rest and in transit. Use HTTPS to secure API communication.
  - **Rate Limiting**: Implement rate limiting to prevent denial-of-service (DoS) attacks.
  - **Query Complexity Analysis**: Limit the complexity of GraphQL queries to prevent malicious users from overloading the server. Tools like `graphql-cost-analysis` can help.

- **Testing Approaches**:
  - **Unit Testing**: Write unit tests for your resolvers to ensure they are functioning correctly.
  - **Integration Testing**:  Write integration tests to verify that your GraphQL API integrates correctly with your data sources and other services.
  - **End-to-end Testing**:  Write end-to-end tests to simulate user interactions with your API and verify that the entire system is working as expected.
  - **Test Organization**: Organize your tests into a logical directory structure. Use clear and descriptive names for your test files.
  - **Mocking and Stubbing**: Use mocking and stubbing to isolate your resolvers from external dependencies during testing.

- **Common Pitfalls and Gotchas**:
  - **N+1 Problem**: Be aware of the N+1 problem, where fetching a list of items requires N additional queries to fetch related data. Use DataLoader to batch and cache these queries.
  - **Circular Dependencies**: Avoid circular dependencies between your schema types, as this can lead to errors.

- **Tooling and Environment**:
  - **Recommended Development Tools**: Use tools like GraphQL Playground or GraphiQL for exploring and testing your API. Consider using a GraphQL IDE like Apollo Studio or Altair GraphQL Client for advanced features.
  - **Linting and Formatting**: Use a GraphQL linter and formatter to enforce code style and prevent errors.  Consider using ESLint with the `eslint-plugin-graphql` plugin.
  - **Deployment Best Practices**:  Deploy your GraphQL API behind a CDN to improve performance and availability.  Use a GraphQL gateway to manage authentication, authorization, and rate limiting.
  - **CI/CD Integration**: Integrate your GraphQL API into your CI/CD pipeline to automate testing and deployment.