graphql-expert-best-practices

GraphQL Expert Best Practices Comprehensive performance optimization and best practices guide for GraphQL APIs. Contains rules for resolver optimization, query performance, data fetching patterns, and schema design, prioritized by impact to guide automated refactoring and code generation. When to Apply Reference these guidelines when: Writing GraphQL schemas, resolvers, or type definitions Implementing data fetching and resolver logic Reviewing GraphQL code for performance issues Refactoring existing GraphQL APIs Optimizing query execution or resolver performance Designing GraphQL server architecture Rule Categories by Priority Priority Category Impact Prefix 1 Query Optimization CRITICAL dataloader- 2 Schema Design CRITICAL-HIGH schema- 3 Mutation Design CRITICAL-HIGH mutation- 4 Pagination HIGH pagination- 5 Security CRITICAL-MEDIUM security- 6 Operations MEDIUM operations- Quick Reference dataloader-n-plus-one - Use DataLoader to batch queries and prevent N+1 performance issues query-unique-identifiers - Use unique identifiers over composite parameters to simplify API surface schema-no-json-filters - Ban arbitrary JSON filter scalars to prevent NoSQL injection vulnerabilities schema-no-binary-data - Avoid large binary data in schema to prevent payload bloat and memory issues schema-stable-identifiers - Use globally stable opaque identifiers to prevent information leakage and enumeration attacks schema-structured-types - Use structured types over unstructured String/JSON fields to improve type safety schema-split-types-by-role - Split types by role to prevent privacy field leakage and eliminate runtime authorization schema-prefer-deprecation - Prefer deprecation over versioning to enable continuous API evolution schema-field-overload - Avoid field overloads for viewer vs user to prevent security issues and improve API clarity schema-minimize-nullable-args - Minimize nullable arguments to improve API clarity and type safety schema-no-duplicate-fields - Prevent duplicate fields accessible through nested objects to maintain single source of truth mutation-no-file-uploads - Avoid file uploads through GraphQL to prevent memory exhaustion and security vulnerabilities mutation-single-input-object - Use single input object argument instead of multiple scalars to improve API evolvability mutation-union-result-types - Return union types with dedicated success and specific error types for type-safe error handling mutation-explicit-actions - Design mutations around explicit actions rather than generic update patterns mutation-separate-input-types - Separate input types for create and update to improve type safety mutation-avoid-validation-scalars - Avoid custom validation scalars to prevent multi-request error loops pagination-no-default-totalcount - Avoid default totalCount in connections to prevent performance degradation security-complexity-limits - Require complexity and query node limits to prevent resource exhaustion attacks security-disable-introspection - Disable introspection in production to prevent schema disclosure operations-require-client-headers - Require client identification headers for debugging and monitoring How to Use Read individual rule files for detailed explanations and code examples: rules/dataloader-n-plus-one.md rules/query-unique-identifiers.md rules/schema-no-json-filters.md rules/schema-no-binary-data.md rules/schema-stable-identifiers.md rules/schema-structured-types.md rules/schema-split-types-by-role.md rules/schema-prefer-deprecation.md rules/schema-field-overload.md rules/schema-minimize-nullable-args.md rules/schema-no-duplicate-fields.md rules/mutation-no-file-uploads.md rules/mutation-single-input-object.md rules/mutation-union-result-types.md rules/mutation-explicit-actions.md rules/mutation-separate-input-types.md rules/mutation-avoid-validation-scalars.md rules/pagination-no-default-totalcount.md rules/security-complexity-limits.md rules/security-disable-introspection.md rules/operations-require-client-headers.md Each rule file contains: Brief explanation of why it matters When to use and when not to use the pattern Implementation requirements Incorrect code example with explanation Correct code example with explanation Additional context and references