NestJS GraphQL Integration Explained

GraphQL Overview

GraphQL is a query language and runtime environment for APIs. NestJS provides complete GraphQL support through the @nestjs/graphql package, enabling developers to build flexible, efficient GraphQL APIs.

Install Dependencies

bash
npm install @nestjs/graphql graphql apollo-server-express
npm install -D @types/graphql

Basic Configuration

Configure GraphQL Module

typescript
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { join } from 'path';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
      sortSchema: true,
      playground: true,
      introspection: true,
      context: ({ req }) => ({ req }),
    }),
  ],
})
export class AppModule {}

Define Schema

Define Schema Using Decorators

typescript
import { Field, Int, ObjectType, Resolver, Query, Mutation, Args, ID } from '@nestjs/graphql';
import { User } from './entities/user.entity';

@ObjectType()
export class User {
  @Field(() => ID)
  id: number;

  @Field()
  name: string;

  @Field()
  email: string;

  @Field(() => Int)
  age: number;

  @Field()
  isActive: boolean;

  @Field()
  createdAt: Date;

  @Field()
  updatedAt: Date;
}

Define Input Types

typescript
import { InputType, Field } from '@nestjs/graphql';

@InputType()
export class CreateUserInput {
  @Field()
  name: string;

  @Field()
  email: string;

  @Field()
  password: string;

  @Field(() => Int, { nullable: true })
  age?: number;
}

@InputType()
export class UpdateUserInput {
  @Field(() => ID)
  id: number;

  @Field({ nullable: true })
  name?: string;

  @Field({ nullable: true })
  email?: string;

  @Field(() => Int, { nullable: true })
  age?: number;
}

Create Resolver

Basic Resolver

typescript
import { Resolver, Query, Mutation, Args, ID } from '@nestjs/graphql';
import { UsersService } from './users.service';
import { User } from './entities/user.entity';
import { CreateUserInput, UpdateUserInput } from './dto/user.input';

@Resolver(() => User)
export class UsersResolver {
  constructor(private usersService: UsersService) {}

  @Query(() => [User])
  async users(): Promise<User[]> {
    return this.usersService.findAll();
  }

  @Query(() => User, { nullable: true })
  async user(@Args('id', { type: () => ID }) id: number): Promise<User> {
    return this.usersService.findOne(id);
  }

  @Mutation(() => User)
  async createUser(@Args('input') input: CreateUserInput): Promise<User> {
    return this.usersService.create(input);
  }

  @Mutation(() => User, { nullable: true })
  async updateUser(@Args('input') input: UpdateUserInput): Promise<User> {
    return this.usersService.update(input.id, input);
  }

  @Mutation(() => Boolean)
  async deleteUser(@Args('id', { type: () => ID }) id: number): Promise<boolean> {
    return this.usersService.remove(id);
  }
}

Use Custom Decorators

typescript
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);

// Use in Resolver
@Mutation(() => User)
async createUser(
  @Args('input') input: CreateUserInput,
  @CurrentUser() user: any,
): Promise<User> {
  return this.usersService.create(input, user.id);
}

Relationships and Loading

One-to-One Relationship

typescript
@ObjectType()
export class Profile {
  @Field(() => ID)
  id: number;

  @Field()
  bio: string;

  @Field(() => User)
  user: User;
}

@ObjectType()
export class User {
  @Field(() => ID)
  id: number;

  @Field()
  name: string;

  @Field(() => Profile, { nullable: true })
  profile?: Profile;
}

One-to-Many Relationship

typescript
@ObjectType()
export class Post {
  @Field(() => ID)
  id: number;

  @Field()
  title: string;

  @Field()
  content: string;

  @Field(() => User)
  author: User;
}

@ObjectType()
export class User {
  @Field(() => ID)
  id: number;

  @Field()
  name: string;

  @Field(() => [Post])
  posts: Post[];
}

Many-to-Many Relationship

typescript
@ObjectType()
export class Tag {
  @Field(() => ID)
  id: number;

  @Field()
  name: string;

  @Field(() => [Post])
  posts: Post[];
}

@ObjectType()
export class Post {
  @Field(() => ID)
  id: number;

  @Field()
  title: string;

  @Field(() => [Tag])
  tags: Tag[];
}

typescript
import { ArgsType, Field, Int } from '@nestjs/graphql';

@ArgsType()
export class PaginationArgs {
  @Field(() => Int, { nullable: true })
  first?: number;

  @Field(() => String, { nullable: true })
  after?: string;
}

@ObjectType()
export class PaginatedUsers {
  @Field(() => [User])
  data: User[];

  @Field(() => Boolean)
  hasNextPage: boolean;

  @Field(() => String, { nullable: true })
  endCursor?: string;
}

@Resolver(() => User)
export class UsersResolver {
  @Query(() => PaginatedUsers)
  async users(@Args() pagination: PaginationArgs): Promise<PaginatedUsers> {
    const { data, hasNextPage, endCursor } = await this.usersService.paginate(pagination);
    return { data, hasNextPage, endCursor };
  }
}

typescript
@ArgsType()
export class OffsetPaginationArgs {
  @Field(() => Int, { nullable: true, defaultValue: 0 })
  skip?: number;

  @Field(() => Int, { nullable: true, defaultValue: 10 })
  take?: number;
}

@ObjectType()
export class OffsetPaginatedUsers {
  @Field(() => [User])
  data: User[];

  @Field(() => Int)
  total: number;

  @Field(() => Int)
  page: number;

  @Field(() => Int)
  totalPages: number;
}

@Resolver(() => User)
export class UsersResolver {
  @Query(() => OffsetPaginatedUsers)
  async users(@Args() pagination: OffsetPaginationArgs): Promise<OffsetPaginatedUsers> {
    const { data, total, page, totalPages } = await this.usersService.paginate(pagination);
    return { data, total, page, totalPages };
  }
}

Subscriptions

Configure Subscriptions

typescript
import { PubSub } from 'graphql-subscriptions';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      installSubscriptionHandlers: true,
      context: ({ req, connection }) => {
        if (connection) {
          return { req: connection.context };
        }
        return { req };
      },
    }),
  ],
})
export class AppModule {}

Create Subscription Resolver

typescript
import { Resolver, Subscription, Root } from '@nestjs/graphql';
import { PubSub } from 'graphql-subscriptions';

@ObjectType()
export class Message {
  @Field(() => ID)
  id: number;

  @Field()
  content: string;

  @Field()
  createdAt: Date;
}

@Resolver(() => Message)
export class MessagesResolver {
  private pubSub: PubSub;

  constructor() {
    this.pubSub = new PubSub();
  }

  @Subscription(() => Message, {
    filter: (payload, variables) => {
      return payload.chatId === variables.chatId;
    },
  })
  messageAdded(@Root() message: Message, @Args('chatId') chatId: number): Message {
    return message;
  }

  async publishMessage(message: Message) {
    await this.pubSub.publish('messageAdded', { messageAdded: message });
  }
}

Data Loader

Create DataLoader

typescript
import { DataLoader } from 'dataloader';
import { UsersService } from './users.service';

export class UserDataLoader {
  private loader: DataLoader<number, User>;

  constructor(private usersService: UsersService) {
    this.loader = new DataLoader(async (ids) => {
      const users = await this.usersService.findByIds(ids);
      return ids.map(id => users.find(user => user.id === id));
    });
  }

  async load(id: number): Promise<User> {
    return this.loader.load(id);
  }

  async loadMany(ids: number[]): Promise<User[]> {
    return this.loader.loadMany(ids);
  }
}

Use DataLoader in Resolver

typescript
import { Resolver, Query, Args, ID, Parent } from '@nestjs/graphql';
import { UserDataLoader } from './user-dataloader';

@Resolver(() => Post)
export class PostsResolver {
  constructor(private userDataLoader: UserDataLoader) {}

  @Query(() => [Post])
  async posts(): Promise<Post[]> {
    return this.postsService.findAll();
  }

  @FieldResolver(() => User)
  async author(@Parent() post: Post): Promise<User> {
    return this.userDataLoader.load(post.authorId);
  }
}

Validation and Transformation

Use class-validator

typescript
import { IsEmail, IsString, MinLength } from 'class-validator';

@InputType()
export class CreateUserInput {
  @Field()
  @IsEmail()
  email: string;

  @Field()
  @IsString()
  @MinLength(6)
  password: string;

  @Field()
  @IsString()
  name: string;
}

Custom Validators

typescript
import { registerDecorator, ValidationOptions, ValidationArguments } from 'class-validator';

export function IsStrongPassword(validationOptions?: ValidationOptions) {
  return function (object: Object, propertyName: string) {
    registerDecorator({
      name: 'isStrongPassword',
      target: object.constructor,
      propertyName: propertyName,
      options: validationOptions,
      validator: {
        validate(value: any) {
          const hasUpperCase = /[A-Z]/.test(value);
          const hasLowerCase = /[a-z]/.test(value);
          const hasNumber = /[0-9]/.test(value);
          return hasUpperCase && hasLowerCase && hasNumber;
        },
        defaultMessage(args: ValidationArguments) {
          return 'Password must contain uppercase, lowercase, and numbers';
        },
      },
    });
  };
}

@InputType()
export class CreateUserInput {
  @Field()
  @IsStrongPassword()
  password: string;
}

Error Handling

Custom Error Classes

typescript
import { ApolloError } from 'apollo-server-express';

export class UserNotFoundError extends ApolloError {
  constructor(id: number) {
    super(`User with ID ${id} not found`, 'USER_NOT_FOUND', {
      id,
    });
  }
}

export class ValidationError extends ApolloError {
  constructor(message: string, fields: string[]) {
    super(message, 'VALIDATION_ERROR', { fields });
  }
}

Use Errors in Resolver

typescript
@Resolver(() => User)
export class UsersResolver {
  constructor(private usersService: UsersService) {}

  @Query(() => User, { nullable: true })
  async user(@Args('id', { type: () => ID }) id: number): Promise<User> {
    const user = await this.usersService.findOne(id);
    if (!user) {
      throw new UserNotFoundError(id);
    }
    return user;
  }

  @Mutation(() => User)
  async createUser(@Args('input') input: CreateUserInput): Promise<User> {
    try {
      return await this.usersService.create(input);
    } catch (error) {
      throw new ValidationError('Invalid input', error.fields);
    }
  }
}

Permission Control

Create Permission Guard

typescript
import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
import { GqlExecutionContext } from '@nestjs/graphql';

@Injectable()
export class GqlAuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const ctx = GqlExecutionContext.create(context);
    const { req } = ctx.getContext();
    
    if (!req.user) {
      throw new UnauthorizedException();
    }
    
    return true;
  }
}

Use Permission Guard

typescript
import { Resolver, Mutation, UseGuards } from '@nestjs/graphql';
import { GqlAuthGuard } from './guards/gql-auth.guard';

@Resolver(() => User)
export class UsersResolver {
  @Mutation(() => User)
  @UseGuards(GqlAuthGuard)
  async createUser(@Args('input') input: CreateUserInput): Promise<User> {
    return this.usersService.create(input);
  }
}

Performance Optimization

Query Complexity Analysis

typescript
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  validationRules: [
    queryComplexity({
      maximumComplexity: 1000,
      variables: {},
      onComplete: (complexity) => {
        console.log(`Query complexity: ${complexity}`);
      },
    }),
  ],
})

Query Depth Limit

typescript
import { depthLimit } from 'graphql-depth-limit';

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  validationRules: [
    depthLimit(5),
  ],
})

Best Practices

Schema First: Prioritize using Schema First approach
Type Safety: Fully utilize TypeScript's type system
Pagination: Always implement pagination to avoid large data transfers
Data Loaders: Use DataLoader to solve N+1 query problems
Error Handling: Provide clear error messages
Permission Control: Implement appropriate permission control mechanisms
Performance Monitoring: Monitor query performance and complexity
Documentation: Use GraphQL Playground and documentation tools

Summary

NestJS GraphQL integration provides:

Complete GraphQL support
Flexible Schema definition
Powerful type safety
Rich query capabilities
Easy-to-integrate ecosystem

Mastering NestJS GraphQL integration is key to building modern, flexible APIs. By properly using GraphQL features, you can build efficient, type-safe, maintainable APIs that meet frontend's precise data requirements. GraphQL's query language features enable clients to precisely fetch needed data, reducing network transfer and improving performance.

How to integrate GraphQL in NestJS?