graphql-expert-best-practices

Original：🇺🇸 English

Translated

GraphQL performance optimization and best practices for building scalable APIs. This skill should be used when writing, reviewing, or refactoring GraphQL schemas, resolvers, or query execution code. Triggers on tasks involving GraphQL APIs, resolver optimization, query performance, or data fetching patterns.

68installs

Sourcewispbit-ai/skills

Added on2026-02-11

NPX Install

npx skill4agent add wispbit-ai/skills graphql-expert-best-practices

SKILL.md Content

View Translation Comparison →

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


dataloader-
schema-
mutation-
pagination-
security-
operations-

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