Build Graphql Server

Create a production-ready GraphQL server with type-safe schemas, optimized resolvers, real-time subscriptions, authentication, and comprehensive tooling using schema-first design principles.

When to Use This Command

Use /build-graphql-server when you need to:

• Build flexible APIs with client-specified queries
• Implement real-time features with subscriptions
• Reduce over-fetching and under-fetching of data
• Create strongly-typed API contracts
• Support multiple client applications with different data needs
• Build microservices with federation support

DON'T use this when:

• Building simple CRUD APIs (REST may be simpler)
• Clients have limited GraphQL knowledge (learning curve)
• Caching is critical and simple (REST caching is more straightforward)

Design Decisions

This command implements Apollo Server with DataLoader as the primary approach because:

• Most mature GraphQL server implementation
• Excellent TypeScript support
• Built-in performance optimizations
• Rich ecosystem of tools and plugins
• Production-proven at scale
• Comprehensive monitoring with Apollo Studio

Alternative considered: GraphQL Yoga

• More lightweight and modular
• Better for serverless deployments
• Newer with smaller ecosystem
• Recommended for edge computing

Alternative considered: Mercurius (Fastify)

• Fastest GraphQL server
• Better for high-performance requirements
• Less mature ecosystem
• Recommended when performance is critical

Prerequisites

Before running this command:

1. Define your domain models and relationships
2. Choose database and ORM/ODM
3. Plan authentication strategy
4. Determine subscription requirements
5. Identify performance requirements

Implementation Process

Step 1: Design GraphQL Schema

Create comprehensive type definitions with proper nullability and relationships.

Step 2: Implement Resolvers

Build efficient resolvers with DataLoader for batching and caching.

Step 3: Add Authentication & Authorization

Implement context-based auth with field-level permissions.

Step 4: Set Up Subscriptions

Configure WebSocket server for real-time updates.

Step 5: Optimize Performance

Add query complexity analysis, depth limiting, and caching.

Output Format

The command generates:

• schema/ - GraphQL schema definitions
• resolvers/ - Resolver implementations
• dataloaders/ - DataLoader configurations
• directives/ - Custom schema directives
• server.js - Apollo Server setup
• generated/types.ts - TypeScript definitions
• tests/ - Integration and unit tests

Code Examples

Example 1: Complete GraphQL Server with Apollo Server

// schema/schema.graphql
scalar DateTime
scalar Upload

directive @auth(requires: Role = USER) on FIELD_DEFINITION
directive @rateLimit(max: Int, window: String) on FIELD_DEFINITION
directive @deprecated(reason: String) on FIELD_DEFINITION | ENUM_VALUE

enum Role {
  USER
  MODERATOR
  ADMIN
}

type User {
  id: ID!
  username: String!
  email: String!
…

Example 2: Optimized Resolvers with DataLoader

// resolvers/index.js
const { GraphQLScalarType } = require('graphql');
const { PubSub, withFilter } = require('graphql-subscriptions');
const DataLoader = require('dataloader');

const pubsub = new PubSub();

const resolvers = {
  // Custom scalar for DateTime
  DateTime: new GraphQLScalarType({
    name: 'DateTime',
    serialize: (value) => value.toISOString(),
    parseValue: (value) => new Date(value),
    parseLiteral: (ast) => new Date(ast.value)
  }),

  Query: {
    me: async (_, __, { user, loaders }) => {
…

Example 3: Custom Directives and Performance Optimization

// directives/auth.js
const { mapSchema, getDirective, MapperKind } = require('@graphql-tools/utils');
const { defaultFieldResolver } = require('graphql');

function authDirective(schema, directiveName) {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
      const authDirective = getDirective(schema, fieldConfig, directiveName)?.[0];

      if (authDirective) {
        const { requires } = authDirective;
        const { resolve = defaultFieldResolver } = fieldConfig;

        fieldConfig.resolve = async function (source, args, context, info) {
          // Check if user is authenticated
          if (!context.user) {
            throw new Error('Not authenticated');
          }
…

Error Handling

Configuration Options

Server Options

• introspection: Enable schema introspection (disable in production)
• playground: Enable GraphQL Playground
• cors: CORS configuration
• uploads: File upload support
• subscriptions: WebSocket configuration

Performance Options

• depthLimit: Maximum query depth (default: 10)