Building a Type-Safe GraphQL API with NestJS and TypeGraphQL

#nestjs #typescript #api #tutorial

Why Type-Safe GraphQL Matters

Traditional GraphQL development often involves maintaining separate schema definitions and TypeScript interfaces, creating a maintenance nightmare where types can drift apart. Every schema change requires updating multiple files, and there's no guarantee your TypeScript types match your GraphQL schema.

Key benefits of the type-safe approach:

Single source of truth for your types
Compile-time error detection instead of runtime surprises
Auto-generated GraphQL schema from TypeScript classes
Seamless IDE autocomplete and refactoring support
Reduced boilerplate code by up to 50%

Prerequisites

Before we dive in, make sure you have:

Node.js 16+ and npm/yarn installed
Basic understanding of TypeScript and decorators
Familiarity with GraphQL concepts (queries, mutations, types)
Basic knowledge of dependency injection patterns

Setting Up Your NestJS GraphQL Project

Let's start by creating a new NestJS project with all the necessary dependencies:

# Create new NestJS project
npm i -g @nestjs/cli
nest new graphql-api-tutorial

# Navigate to project
cd graphql-api-tutorial

# Install GraphQL dependencies
npm install @nestjs/graphql @nestjs/apollo @apollo/server graphql
npm install --save-dev @types/node

Configuring GraphQL Module

First, let's configure the GraphQL module in your app module:

// src/app.module.ts
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,
    }),
  ],
})
export class AppModule {}

Pro Tip: Setting autoSchemaFile to a path automatically generates and updates your schema file. Use autoSchemaFile: true to keep it in memory only during development.

Creating Your First Object Type

Let's create a User entity that will serve as our GraphQL object type:

// src/users/models/user.model.ts
import { ObjectType, Field, ID, Int } from '@nestjs/graphql';

@ObjectType({ description: 'User model' })
export class User {
  @Field(() => ID)
  id: string;

  @Field()
  email: string;

  @Field()
  username: string;

  @Field({ nullable: true, description: 'User bio' })
  bio?: string;

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

  @Field()
  createdAt: Date;

  // Note: No @Field decorator means this won't be exposed in GraphQL
  password: string;
}