Building GraphQL Server
Overview
Build production-ready GraphQL servers with SDL-first or code-first schema design, efficient resolver implementations with DataLoader batching, real-time subscriptions via WebSocket, and field-level authorization. Support Apollo Server, Yoga, Mercurius, and Strawberry across Node.js and Python runtimes.
Prerequisites
- Node.js 18+ with Apollo Server/Yoga/Mercurius, or Python 3.10+ with Strawberry/Ariadne
- Database with ORM (Prisma, TypeORM, SQLAlchemy) for resolver data sources
- Redis for subscription pub/sub and DataLoader caching (production deployments)
- GraphQL client for testing: GraphiQL, Apollo Studio, or Insomnia
graphql-codegenfor TypeScript type generation from schema (recommended)
Instructions
- Examine existing data models, database schemas, and business requirements using Read and Glob to determine the entity graph and relationship structure.
- Design the GraphQL schema with type definitions, including
Query,Mutation, andSubscriptionroot types, input types for mutations, and connection types for paginated lists. - Implement resolvers for each field, using DataLoader to batch and deduplicate database queries for nested relationships (N+1 query prevention).
- Add input validation on mutation arguments using custom scalars (DateTime, Email, URL) and directive-based validation (
@constraint(minLength: 1, maxLength: 255)). - Implement field-level authorization using schema directives (
@auth(requires: ADMIN)) or resolver middleware that checks user roles from the GraphQL context. - Configure query complexity analysis and depth limiting to prevent abusive queries (maximum depth of 7, maximum complexity score of 1000).
- Set up real-time subscriptions using
graphql-wsprotocol over WebSocket with Redis pub/sub for multi-instance message distribution. - Generate TypeScript types from the schema using
graphql-codegento ensure type safety between schema definitions and resolver implementations. - Write integration tests using
executeOperationfor query/mutation testing and WebSocket client tests for subscription verification.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/src/schema/- GraphQL SDL type definitions organized by domain${CLAUDE_SKILL_DIR}/src/resolvers/- Resolver implementations per type with DataLoader integration${CLAUDE_SKILL_DIR}/src/dataloaders/- DataLoader factories for batched database queries${CLAUDE_SKILL_DIR}/src/directives/- Custom schema directives (auth, validation, caching)${CLAUDE_SKILL_DIR}/src/scalars/- Custom scalar type definitions (DateTime, JSON, Email)${CLAUDE_SKILL_DIR}/src/subscriptions/- Subscription resolvers with pub/sub configuration${CLAUDE_SKILL_DIR}/generated/types.ts- Auto-generated TypeScript types from schema
Error Handling
| Error | Cause | Solution |
|---|---|---|
| N+1 query detected | Resolver fetches related records individually inside list resolver | Wrap data access in DataLoader; batch by parent ID array; cache within request scope |
| Query complexity exceeded | Client sends deeply nested query exceeding complexity budget | Return error with current complexity score and maximum allowed; suggest query simplification |
| Subscription connection dropped | WebSocket heartbeat timeout or network interruption | Implement automatic reconnection in client; use graphql-ws connectionInitWaitTimeout |
| Partial resolver failure | One field resolver throws while others succeed | Return partial data with errors array per GraphQL spec; log failed resolver with context |
| Schema stitching conflict | Duplicate type names when merging multiple schema modules | Use schema namespacing or federation with @key directives to resolve type ownership |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
E-commerce product catalog: Schema with Product, Category, Review types, DataLoader-backed resolvers for nested queries like products {reviews {author}}, and a productUpdated subscription for inventory changes.
Multi-tenant SaaS dashboard: Code-first schema using TypeGraphQL decorators, tenant-scoped resolvers extracting tenantId from JWT context, and field-level visibility based on subscription plan tier.
Federated microservice graph: Apollo Federation with @key and @external directives across User, Order, and Product subgraphs, composed into a unified supergraph with a gateway router.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
- GraphQL Specification: https://spec.graphql.org/
- Apollo Server documentation: https://www.apollographql.com/docs/apollo-server/
- DataLoader pattern: https://github.com/graphql/dataloader
graphql-wsprotocol: https://github.com/enisdenjo/graphql-ws