NestJS and GraphQL Tutorial: Build a Scalable API

NestJS is a modern Node.js framework designed to create highly efficient, dependable, and scalable server-side applications. Combining it with GraphQL allows developers to create powerful, flexible APIs. This tutorial provides a step-by-step guide to building a NestJS app with GraphQL integration.

1. What is NestJS?

Known for its flexibility, NestJS is a feature-rich framework built on top of Express.js, with an option to switch to Fastify for enhanced performance. With its modular architecture and TypeScript support, it’s ideal for creating enterprise-grade applications.

Key features:

TypeScript: A first-class citizen.
Dependency Injection: Simplifies service management.
Scalable Architecture: Designed to support complex applications.

2. Why Use GraphQL with NestJS?

GraphQL functions as both a powerful query language and a runtime, enabling seamless interaction with APIs. It offers clients the ability to request exactly the data they need, unlike traditional REST APIs. Here's why combining it with NestJS is a game-changer:

Flexibility: Clients request specific fields.
Performance: Reduces over-fetching and under-fetching of data.
Schema-Driven Development: Strongly typed schemas improve collaboration.

3. Prerequisites

To get started, ensure you have the necessary tools and software installed beforehand:

Node.js: Version 16 or later.
NestJS CLI: Install using npm install -g @nestjs/cli.
Basic Knowledge: Familiarity with TypeScript and GraphQL.

4. Setting Up the NestJS Project

Create a New NestJS App

Run the following command to scaffold a new NestJS project:

nest new nestjs-graphql-tutorial

Select the package manager that best fits your workflow—npm, yarn, or pnpm are all viable options.

Install Dependencies

Navigate to the project directory and install GraphQL-related packages:

npm install @nestjs/graphql graphql-tools graphql apollo-server-express

Project Structure

A typical NestJS project structure looks like this:

src/
├── app.module.ts
├── main.ts
├── graphql/
    ├── user.resolver.ts
    ├── user.service.ts
    ├── user.schema.ts

5. Installing and Configuring GraphQL

Install GraphQL Module

Import the GraphQLModule in your app.module.ts:

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { join } from 'path';

@Module({
  imports: [
    GraphQLModule.forRoot({
      autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
    }),
  ],
})
export class AppModule {}

Enable Auto Schema Generation

The autoSchemaFile option generates the GraphQL schema automatically based on your resolvers.

6. Defining a GraphQL Schema

Create a simple User schema.

Define User Entity

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

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

  @Field()
  name: string;

  @Field()
  email: string;
}

Update Module Structure

Update the AppModule to include the User module:

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { UserModule } from './user/user.module';

@Module({
  imports: [
    GraphQLModule.forRoot({ autoSchemaFile: true }),
    UserModule,
  ],
})
export class AppModule {}

7. Creating Resolvers in NestJS

Create a Resolver

Resolvers map GraphQL queries to underlying services:

import { Resolver, Query, Args } from '@nestjs/graphql';
import { User } from './user.entity';

@Resolver(() => User)
export class UserResolver {
  private users = [
    { id: 1, name: 'John Doe', email: 'john@example.com' },
    { id: 2, name: 'Jane Doe', email: 'jane@example.com' },
  ];

  @Query(() => [User])
  getUsers(): User[] {
    return this.users;
  }

  @Query(() => User)
  getUser(@Args('id', { type: () => Int }) id: number): User {
    return this.users.find(user => user.id === id);
  }
}

Create a Service

Add a UserService to handle business logic:

import { Injectable } from '@nestjs/common';
import { User } from './user.entity';

@Injectable()
export class UserService {
  private users: User[] = [
    { id: 1, name: 'John Doe', email: 'john@example.com' },
    { id: 2, name: 'Jane Doe', email: 'jane@example.com' },
  ];

  findAll(): User[] {
    return this.users;
  }

  findOneById(id: number): User {
    return this.users.find(user => user.id === id);
  }
}

8. Testing Your GraphQL API

Start the Server

Run the application:

npm run start

The GraphQL Playground is available at http://localhost:3000/graphql.

Sample Queries

Test your API with the following query:

query {
  getUsers {
    id
    name
    email
  }
}

The combination of NestJS and GraphQL offers a robust framework for creating efficient and scalable APIs tailored to modern application needs. This tutorial covered the fundamentals of setting up a project, creating schemas, and implementing resolvers. As you grow your application, consider adding features like authentication, data validation, and database integration.

Further Reading: