NestJS Tutorial: Build a REST API in 13 Steps [2026]

NestJS has become the default choice for teams that want the structure of an enterprise framework without leaving the Node.js ecosystem. With 9,900 monthly U.S. searches for “nestjs” in March 2026 and the latest release, v12.1.3, landing on GitHub in October 2026 as the framework’s newest tagged release — following v12.1.1 on September 28, 2026 and the v12.0.0 launch itself in August 2026, which delivered ESM-ready packages and Standard Schema support — the framework has long since dropped Node.js 16 and 18 support and has now fully shipped the full-ESM rewrite it spent early 2026 previewing.

This tutorial walks you through building a production-ready REST API in 13 steps using NestJS 11, Node.js 20 LTS, TypeScript 5.x, PostgreSQL via Prisma, JWT authentication, OpenAPI documentation, validation pipes, global exception filters, request-scoped logging, and a complete Jest test suite. Every code block has been verified against the NestJS 11 release line — spanning v11.1.14 in February 2026 through v11.1.28 in July 2026 — with the tutorial itself last refreshed in August 2026 to keep pace with the framework’s fast-moving changelog.

·

Google · Preferred Sources

Don't miss new tech stories on Google

Add Tech Insider once in the Google app and our stories appear in your news suggestions.

Add Now

Why NestJS Dominates Enterprise Node.js in 2026

NestJS, created by Kamil Myśliwiec and first released in 2017, has spent the last nine years quietly becoming the most opinionated, most testable, and most maintainable way to build server-side TypeScript applications on Node.js. Where Express.js gives you an unstructured pile of middleware and Fastify gives you a faster but still unstructured pile of middleware, NestJS gives you modules, controllers, providers, dependency injection, decorators, guards, interceptors, pipes, and exception filters out of the box. That architecture is borrowed almost verbatim from Angular, which is no accident: Myśliwiec wanted Node.js to have the same level of large-team discipline that Angular brings to the frontend.

By late 2026, the numbers tell the story. The nestjs/nest GitHub repository had crossed 180,000 GitHub stars, the core packages were pulling roughly 2.5 million weekly npm downloads, and the framework is in production at Adidas, Capgemini, Roche, Decathlon, Société Générale, and dozens of Fortune 500 teams that picked NestJS specifically because its rigid structure scales across hundreds of engineers without devolving into Express-style spaghetti. The v11 release line, which is the focus of this tutorial, made Express v5 the default adapter — a change solidified across the minor releases that followed, including v11.1.14 in February 2026 — modernized the Reflector API, and tightened TypeScript decorator semantics in ways that pay off the moment your team grows past three developers, a foundation the project then built on with the v12.0.0 launch in August 2026 and the v12.1.3 release in October 2026.

The framework’s appeal is not raw throughput. Plain Express can handle more requests per second in microbenchmarks, and Fastify can almost double that throughput again. NestJS is roughly 8 to 12 percent slower than its underlying adapter because every request passes through middleware, guards, interceptors, pipes, the controller, the service, the return-path interceptors, and any exception filters. That overhead is the price of admission for a request lifecycle that is consistent, testable, and debuggable in a way that hand-rolled Express applications never manage to be. For most production REST APIs, where database round-trips dominate latency, the framework cost is invisible. For latency-critical endpoints, NestJS lets you swap the adapter to Fastify with a one-line change.

NestJS 11 vs the Wider Node.js Backend Landscape

Before we write any code, it is worth grounding the tutorial in a comparison so you understand why we are choosing NestJS over the alternatives. The table below compares NestJS 11 against the four other backends a 2026 team is likely to evaluate: bare Express v5, Fastify 5, Hono, and Adonis 6. All figures come from the official documentation, GitHub releases, and the published changelogs as of October 2026, by which point NestJS had moved past the v11 line entirely and shipped v12.1.3 as its latest tagged GitHub release, just weeks after v12.1.1 landed on September 28, 2026.

Framework	Latest version (Apr 2026)	Default adapter	DI built-in	TypeScript-first	Best for
NestJS	11.1.20	Express v5	Yes	Yes	Large teams, enterprise REST/GraphQL/microservices
Express.js	5.x	n/a	No	No (types via DefinitelyTyped)	Tiny services, prototypes, legacy
Fastify	5.x	n/a	No	Partial	High-throughput JSON APIs
Hono	4.x	n/a	No	Yes	Edge runtimes (Cloudflare, Deno, Bun)
Adonis	6.x	Custom (Node http)	Yes	Yes	Laravel-style monolith

The pattern is clear: if you want a framework that imposes structure, gives you dependency injection without an external container, and matches the way a team of 50 engineers reasons about boundaries, NestJS is the only option in that table. Hono is a far better choice if you are deploying to Cloudflare Workers, and Fastify wins if you genuinely need every microsecond of throughput, but for the typical REST API that backs a SaaS product, NestJS pays for itself within the first sprint.

Step 1: Prerequisites and Environment Setup

NestJS 11 has a hard floor of Node.js 20, and the newer NestJS v12.0.0 line, which launched in August 2026 with ESM-ready packages and Standard Schema support, raises that floor further to Node.js 20.19+ or 22.12+ as documented by Tle Apps. Trilon shipped NestJS v11.0.0 in January 2025, formally dropping Node.js 16 and 18 support in that release — DevRadar’s NestJS v11 profile, last refreshed in January 2026, still cites that same January 2025 date as the framework’s major-version cutover — and the timing lines up with Node.js 18’s security support ending on April 30, 2025. If you are still on an older version, upgrade before continuing. For this tutorial you will need the following installed, with the exact versions verified against the current NestJS 11.2.x line, which by August 2026 had already progressed through v11.1.28 in July and on to v11.2.1 shortly after, ahead of the project’s move to the v12.1.3 release in October 2026.

Tool	Minimum version	Recommended version (April 2026)	Check command
Node.js	20.0.0	22.14.0 LTS	node –version
npm	10.0.0	10.9.x	npm –version
TypeScript	5.4	5.7.x	tsc –version
NestJS CLI	11.0.0	11.0.10	nest –version
PostgreSQL	14	17.x	psql –version
Docker (optional)	24	27.x	docker –version

If you are on a Mac with Apple Silicon, use Homebrew to install Node.js 22 LTS with brew install node@22. On Linux, install via the official NodeSource repository or, even better, via a version manager like nvm so you can switch between Node.js 20 and 22 without breaking projects. On Windows, install via the official MSI from nodejs.org or use winget with winget install OpenJS.NodeJS.LTS. Then install the NestJS CLI globally:

# Verify Node.js 20+ is installed
node --version
# v22.14.0

# Install NestJS CLI globally
npm install -g @nestjs/cli@11

# Verify the CLI version
nest --version
# 11.0.10

# Confirm PostgreSQL is reachable
psql --version
# psql (PostgreSQL) 17.2

Pitfall #1: Do not install the NestJS CLI without the @11 tag if you cloned a tutorial that targets v10. The CLI generates slightly different boilerplate across major versions, and a v10 CLI will scaffold a project that is missing the Express v5 type fixes that v11 introduced. Always pin the CLI to the major version of the framework you intend to use.

Step 2: Scaffold the Project with the NestJS CLI

The NestJS CLI is the single biggest productivity advantage the framework has over hand-rolled alternatives. The nest new command does not just create a folder; it scaffolds a complete TypeScript project with a working Jest configuration, ESLint and Prettier preconfigured, a sample controller, a sample service, a root module, and a main bootstrap file. For this tutorial we will create a project called nest-store-api, the backend for a fictional e-commerce product catalog.

# Create the project (pick npm when prompted)
nest new nest-store-api --strict --package-manager npm

# Enter the project
cd nest-store-api

# Run the dev server
npm run start:dev

# Expected output:
# [Nest] LOG [NestFactory] Starting Nest application...
# [Nest] LOG [InstanceLoader] AppModule dependencies initialized
# [Nest] LOG [RoutesResolver] AppController {/}
# [Nest] LOG [RouterExplorer] Mapped {/, GET} route
# [Nest] LOG [NestApplication] Nest application successfully started

Open http://localhost:3000 in your browser. You should see the classic NestJS “Hello World!” response. The --strict flag enables TypeScript strict mode in tsconfig.json, which adds strictNullChecks, noImplicitAny, strictFunctionTypes, and the other strict family flags. In a production codebase this is non-negotiable; without strict mode you give up most of the safety guarantees that motivated using TypeScript in the first place.

Look at the file structure the CLI created. The src/main.ts file bootstraps the application by calling NestFactory.create(AppModule) and calling listen(3000). src/app.module.ts is the root module that imports controllers and providers. src/app.controller.ts is a sample HTTP controller. src/app.service.ts is a sample provider. The pattern of module + controller + service is the unit you will repeat hundreds of times in any NestJS application, so spend a few minutes reading the four generated files before continuing.

Step 3: Generate the Products Resource

The CLI’s most powerful command is nest generate resource, which scaffolds a full CRUD resource with a controller, a service, a module, DTOs, and entity stubs in a single command. We will use it to create the products domain that the rest of the tutorial will revolve around.

# Generate the products resource (pick "REST API" when prompted, "yes" for CRUD)
nest g resource products

# Inspect what got created
ls src/products
# dto/
# entities/
# products.controller.spec.ts
# products.controller.ts
# products.module.ts
# products.service.spec.ts
# products.service.ts

The generated controller already has stub handlers for the five canonical CRUD verbs: POST /products, GET /products, GET /products/:id, PATCH /products/:id, and DELETE /products/:id. The service has matching method stubs that return placeholder strings. The DTO classes in src/products/dto/ are empty TypeScript classes ready for validation decorators. The entity in src/products/entities/ is the placeholder we will replace with a Prisma model in Step 6.

Pitfall #2: The generated products.module.ts is automatically registered in app.module.ts by the CLI. If you later rename or move a module manually, you must update the imports array in the parent module yourself. NestJS will fail at startup with a cryptic Nest can't resolve dependencies of the X (?) error if a provider is referenced from a module that does not export it.

Step 4: Fill in the DTOs with class-validator

Data Transfer Objects (DTOs) are the contract between the outside world and your service layer. NestJS does not validate request bodies automatically; you have to opt in with the ValidationPipe and decorate your DTOs with class-validator rules. This pair, combined with class-transformer, is the canonical NestJS validation stack and the pattern you will use in every controller you ever write.

npm install class-validator class-transformer

Replace the contents of src/products/dto/create-product.dto.ts with a DTO that declares the shape and constraints of an incoming product creation request:

import { IsString, IsNumber, IsOptional, IsInt, Min, MaxLength } from 'class-validator';

export class CreateProductDto {
  @IsString()
  @MaxLength(120)
  name: string;

  @IsOptional()
  @IsString()
  @MaxLength(2000)
  description?: string;

  @IsNumber({ maxDecimalPlaces: 2 })
  @Min(0)
  priceUsd: number;

  @IsInt()
  @Min(0)
  stock: number;

  @IsOptional()
  @IsString()
  sku?: string;
}

The UpdateProductDto in update-product.dto.ts was generated as PartialType(CreateProductDto), which is the NestJS idiom for “every field is optional but obeys the same rules as the create DTO.” That is exactly the semantics of HTTP PATCH and it costs you zero lines of code thanks to the @nestjs/mapped-types helper that the CLI already wired up.

Now wire the global validation pipe in src/main.ts so every controller receives validated and transformed bodies:

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
      transformOptions: { enableImplicitConversion: true },
    }),
  );

  await app.listen(3000);
}
bootstrap();

The four options on ValidationPipe are the production-grade default. whitelist strips any property not declared on the DTO; forbidNonWhitelisted rejects the request with a 400 if extra properties are sent (very useful for spotting client bugs); transform turns the plain JSON object into an instance of the DTO class so instanceof works; enableImplicitConversion coerces string query parameters into the declared TypeScript types like number or boolean.

Step 5: Add a Configuration Module with @nestjs/config

Hard-coding the database URL, JWT secret, and port number into your code is the fastest path to a security incident. NestJS ships with @nestjs/config, a thin but well-designed wrapper around dotenv that adds schema validation, namespacing, and dependency-injection of configuration values into your services.

npm install @nestjs/config joi

Create a .env file at the project root (and add it to .gitignore):

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/nest_store?schema=public"
JWT_SECRET="change-me-to-a-256-bit-random-string"
JWT_EXPIRES_IN="3600s"
PORT=3000
NODE_ENV=development

Register the config module globally and add a Joi schema so the application refuses to start if a required env var is missing or malformed. Edit src/app.module.ts:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import * as Joi from 'joi';
import { ProductsModule } from './products/products.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      cache: true,
      validationSchema: Joi.object({
        NODE_ENV: Joi.string().valid('development', 'test', 'production').default('development'),
        PORT: Joi.number().default(3000),
        DATABASE_URL: Joi.string().uri({ scheme: ['postgresql'] }).required(),
        JWT_SECRET: Joi.string().min(32).required(),
        JWT_EXPIRES_IN: Joi.string().default('3600s'),
      }),
    }),
    ProductsModule,
  ],
})
export class AppModule {}

Now restart with npm run start:dev. If you omit JWT_SECRET or set it shorter than 32 characters, the application crashes at startup with a clear validation error. This is exactly the behavior you want; the alternative is a runtime crash three weeks later in production when a request happens to hit the auth code path.

Step 6: Wire Up Prisma 6 for PostgreSQL Persistence

NestJS is ORM-agnostic. You can use TypeORM, Sequelize, Mongoose, Drizzle, or Prisma. For new projects in 2026, Prisma is the recommended choice because of its type-safe client, mature migration tooling, and excellent PostgreSQL support. The integration with NestJS is straightforward: create a PrismaService that extends PrismaClient and inject it into the modules that need database access.

npm install prisma --save-dev
npm install @prisma/client

# Initialize Prisma in the project
npx prisma init --datasource-provider postgresql

# Edit prisma/schema.prisma to add the Product model (see below), then:
npx prisma migrate dev --name init
npx prisma generate

Edit prisma/schema.prisma to declare the Product and User models we will need later:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Product {
  id          String   @id @default(cuid())
  name        String
  description String?
  priceUsd    Decimal  @db.Decimal(10, 2)
  stock       Int      @default(0)
  sku         String?  @unique
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model User {
  id           String   @id @default(cuid())
  email        String   @unique
  passwordHash String
  role         Role     @default(USER)
  createdAt    DateTime @default(now())
}

enum Role {
  USER
  ADMIN
}

Create the Prisma service as a NestJS provider. Add src/prisma/prisma.service.ts:

import { Injectable, OnModuleInit, OnModuleDestroy, Logger } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
  private readonly logger = new Logger(PrismaService.name);

  async onModuleInit() {
    await this.$connect();
    this.logger.log('Prisma connected to PostgreSQL');
  }

  async onModuleDestroy() {
    await this.$disconnect();
    this.logger.log('Prisma disconnected');
  }
}

And the corresponding module at src/prisma/prisma.module.ts:

import { Global, Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class PrismaModule {}

Then import PrismaModule in AppModule. The @Global() decorator means you do not have to re-import PrismaModule in every feature module that uses the service. For a small project that is convenient; for a very large project, prefer explicit imports to keep boundaries clean.

Step 7: Implement the Products Service Against Prisma

Now rewrite the auto-generated products.service.ts to actually persist data. This is where the dependency-injection pays off: the PrismaService is injected via the constructor, and the service has no idea where Prisma is configured.

import { Injectable, NotFoundException } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { CreateProductDto } from './dto/create-product.dto';
import { UpdateProductDto } from './dto/update-product.dto';

@Injectable()
export class ProductsService {
  constructor(private readonly prisma: PrismaService) {}

  create(dto: CreateProductDto) {
    return this.prisma.product.create({ data: dto });
  }

  findAll(skip = 0, take = 20) {
    return this.prisma.product.findMany({
      skip,
      take,
      orderBy: { createdAt: 'desc' },
    });
  }

  async findOne(id: string) {
    const product = await this.prisma.product.findUnique({ where: { id } });
    if (!product) throw new NotFoundException(`Product ${id} not found`);
    return product;
  }

  async update(id: string, dto: UpdateProductDto) {
    await this.findOne(id);
    return this.prisma.product.update({ where: { id }, data: dto });
  }

  async remove(id: string) {
    await this.findOne(id);
    await this.prisma.product.delete({ where: { id } });
    return { deleted: true, id };
  }
}

The controller in src/products/products.controller.ts needs only minor tweaks to pass the DTO and ID through:

import { Controller, Get, Post, Body, Patch, Param, Delete, Query, ParseIntPipe } from '@nestjs/common';
import { ProductsService } from './products.service';
import { CreateProductDto } from './dto/create-product.dto';
import { UpdateProductDto } from './dto/update-product.dto';

@Controller('products')
export class ProductsController {
  constructor(private readonly products: ProductsService) {}

  @Post()
  create(@Body() dto: CreateProductDto) {
    return this.products.create(dto);
  }

  @Get()
  findAll(
    @Query('skip', new ParseIntPipe({ optional: true })) skip?: number,
    @Query('take', new ParseIntPipe({ optional: true })) take?: number,
  ) {
    return this.products.findAll(skip, take);
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.products.findOne(id);
  }

  @Patch(':id')
  update(@Param('id') id: string, @Body() dto: UpdateProductDto) {
    return this.products.update(id, dto);
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return this.products.remove(id);
  }
}

Test the full flow with curl:

curl -X POST http://localhost:3000/products 
  -H 'Content-Type: application/json' 
  -d '{"name":"Mechanical Keyboard","priceUsd":129.99,"stock":42,"sku":"KB-001"}'

# Response:
# {
#   "id": "clx1234567890",
#   "name": "Mechanical Keyboard",
#   "description": null,
#   "priceUsd": "129.99",
#   "stock": 42,
#   "sku": "KB-001",
#   "createdAt": "2026-04-19T14:32:11.123Z",
#   "updatedAt": "2026-04-19T14:32:11.123Z"
# }

Step 8: Add JWT Authentication with Passport

Authentication is the second-most-common feature you will add to any NestJS API. The official pattern uses @nestjs/passport, @nestjs/jwt, and the passport-jwt strategy. This combination is documented in the official NestJS Security guide and has been the recommended approach since v6.

npm install @nestjs/passport @nestjs/jwt passport passport-jwt passport-local bcrypt
npm install -D @types/passport-jwt @types/passport-local @types/bcrypt

# Generate the auth module, controller, and service
nest g module auth
nest g service auth
nest g controller auth

Create src/auth/auth.service.ts with login and registration logic that hashes passwords with bcrypt and signs JWTs:

import { Injectable, UnauthorizedException, ConflictException } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcrypt';
import { PrismaService } from '../prisma/prisma.service';

@Injectable()
export class AuthService {
  constructor(
    private readonly prisma: PrismaService,
    private readonly jwt: JwtService,
  ) {}

  async register(email: string, password: string) {
    const existing = await this.prisma.user.findUnique({ where: { email } });
    if (existing) throw new ConflictException('Email already registered');
    const passwordHash = await bcrypt.hash(password, 12);
    const user = await this.prisma.user.create({
      data: { email, passwordHash },
    });
    return this.sign(user.id, user.email, user.role);
  }

  async login(email: string, password: string) {
    const user = await this.prisma.user.findUnique({ where: { email } });
    if (!user) throw new UnauthorizedException('Invalid credentials');
    const ok = await bcrypt.compare(password, user.passwordHash);
    if (!ok) throw new UnauthorizedException('Invalid credentials');
    return this.sign(user.id, user.email, user.role);
  }

  private sign(sub: string, email: string, role: string) {
    return {
      accessToken: this.jwt.sign({ sub, email, role }),
      tokenType: 'Bearer',
    };
  }
}

Configure the JWT strategy at src/auth/jwt.strategy.ts:

import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(config: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: config.getOrThrow<string>('JWT_SECRET'),
    });
  }

  async validate(payload: { sub: string; email: string; role: string }) {
    return { id: payload.sub, email: payload.email, role: payload.role };
  }
}

Wire everything into auth.module.ts and create a JwtAuthGuard that you can apply to any controller or route with @UseGuards(JwtAuthGuard). The pattern is documented end-to-end in the official NestJS authentication guide, which is one of the best framework tutorials in the JavaScript ecosystem.

Pitfall #3: Never use the default bcrypt work factor of 10 in production. NestJS examples sometimes show bcrypt.hash(password, 10) for brevity; 12 is the realistic 2026 minimum, and 14 is safer if your traffic profile can absorb the extra 120ms per login.

Step 9: Add OpenAPI/Swagger Documentation

One of NestJS’s underrated strengths is the official OpenAPI integration. With a single import and three lines in main.ts, you get a fully interactive Swagger UI at /api that reflects every controller, DTO, and validation rule you have declared.

npm install @nestjs/swagger

Update src/main.ts:

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }),
  );

  const config = new DocumentBuilder()
    .setTitle('Nest Store API')
    .setDescription('A NestJS 11 reference REST API for the product catalog domain')
    .setVersion('1.0.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

Decorate the DTOs with @ApiProperty to give Swagger UI rich field descriptions. The class-validator decorators alone are enough to derive the type, but a one-line description makes the docs vastly more useful for the frontend team.

import { ApiProperty } from '@nestjs/swagger';
import { IsString, IsNumber, IsInt, Min, MaxLength, IsOptional } from 'class-validator';

export class CreateProductDto {
  @ApiProperty({ example: 'Mechanical Keyboard', maxLength: 120 })
  @IsString()
  @MaxLength(120)
  name: string;

  @ApiProperty({ example: 129.99, minimum: 0 })
  @IsNumber({ maxDecimalPlaces: 2 })
  @Min(0)
  priceUsd: number;

  @ApiProperty({ example: 42, minimum: 0 })
  @IsInt()
  @Min(0)
  stock: number;

  @ApiProperty({ example: 'KB-001', required: false })
  @IsOptional()
  @IsString()
  sku?: string;
}

Restart the dev server and visit http://localhost:3000/api. You will see a fully styled Swagger UI with every endpoint, every DTO, and a “Try it out” button that hits your live API. For frontend teams this is a force multiplier; nobody needs to maintain Postman collections by hand any more.

Step 10: Global Exception Filter and Logging Interceptor

By default, NestJS returns reasonable HTTP errors when you throw HttpException or one of its subclasses like NotFoundException and UnauthorizedException. For a production API you almost always want to normalize the response shape, add a request ID, and log unexpected errors with their stack trace. The idiomatic way to do that is a global exception filter combined with a logging interceptor.

// src/common/filters/all-exceptions.filter.ts
import { Catch, ArgumentsHost, HttpException, HttpStatus, Logger, ExceptionFilter } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger(AllExceptionsFilter.name);

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse<Response>();
    const req = ctx.getRequest<Request>();

    const status =
      exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
    const message =
      exception instanceof HttpException ? exception.getResponse() : 'Internal server error';

    if (status >= 500) {
      this.logger.error(`${req.method} ${req.url} -> ${status}`, (exception as Error)?.stack);
    }

    res.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: req.url,
      error: typeof message === 'string' ? message : (message as any).message,
    });
  }
}

Register the filter globally in main.ts with app.useGlobalFilters(new AllExceptionsFilter()). Now every error, whether it is a thrown NotFoundException, a Zod validation failure, or a runtime TypeError, returns a consistent JSON shape with a timestamp and the path, and 5xx errors are logged with their full stack trace.

For request logging, an interceptor is the right tool:

// src/common/interceptors/logging.interceptor.ts
import { CallHandler, ExecutionContext, Injectable, Logger, NestInterceptor } from '@nestjs/common';
import { Observable, tap } from 'rxjs';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger('HTTP');

  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const req = ctx.switchToHttp().getRequest();
    const start = Date.now();
    return next.handle().pipe(
      tap(() => {
        const ms = Date.now() - start;
        this.logger.log(`${req.method} ${req.url} ${ms}ms`);
      }),
    );
  }
}

Register with app.useGlobalInterceptors(new LoggingInterceptor()). The output looks like [Nest] LOG [HTTP] GET /products 12ms, which is exactly what you want shipped to your APM tool of choice.

Step 11: Write the Jest Test Suite

NestJS scaffolds a Jest configuration with nest new and generates *.spec.ts files alongside every controller and service. NestJS 11 still defaults to Jest (the v12 roadmap mentions Vitest, but it is not yet stable). The framework provides a Test.createTestingModule helper that builds a real DI container for tests so you can compose realistic integration tests without spinning up the full HTTP server.

// src/products/products.service.spec.ts
import { Test } from '@nestjs/testing';
import { ProductsService } from './products.service';
import { PrismaService } from '../prisma/prisma.service';
import { NotFoundException } from '@nestjs/common';

describe('ProductsService', () => {
  let service: ProductsService;
  const prismaMock = {
    product: {
      create: jest.fn(),
      findMany: jest.fn(),
      findUnique: jest.fn(),
      update: jest.fn(),
      delete: jest.fn(),
    },
  };

  beforeEach(async () => {
    const moduleRef = await Test.createTestingModule({
      providers: [
        ProductsService,
        { provide: PrismaService, useValue: prismaMock },
      ],
    }).compile();

    service = moduleRef.get(ProductsService);
    jest.clearAllMocks();
  });

  it('creates a product', async () => {
    prismaMock.product.create.mockResolvedValueOnce({ id: '1', name: 'Test' });
    const result = await service.create({
      name: 'Test', priceUsd: 9.99, stock: 5,
    } as any);
    expect(result).toEqual({ id: '1', name: 'Test' });
    expect(prismaMock.product.create).toHaveBeenCalledTimes(1);
  });

  it('throws NotFoundException when product missing', async () => {
    prismaMock.product.findUnique.mockResolvedValueOnce(null);
    await expect(service.findOne('does-not-exist')).rejects.toThrow(NotFoundException);
  });
});

Run the tests:

npm test

# PASS  src/products/products.service.spec.ts
#   ProductsService
#     ok creates a product (4 ms)
#     ok throws NotFoundException when product missing (2 ms)
#
# Tests:       2 passed, 2 total
# Time:        1.847 s

For end-to-end tests, the CLI also generates test/app.e2e-spec.ts that uses supertest to fire real HTTP requests against the bootstrapped application. Run them with npm run test:e2e. In CI, gate merges on both unit and e2e test suites passing.

Step 12: Add Rate Limiting and Helmet for Production

Two production essentials that NestJS leaves to you: rate limiting and HTTP security headers. The official packages @nestjs/throttler and helmet cover both in less than fifty lines of code.

npm install @nestjs/throttler helmet

Register the throttler module globally in app.module.ts:

import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
import { APP_GUARD } from '@nestjs/core';

@Module({
  imports: [
    // ...existing imports
    ThrottlerModule.forRoot([
      { name: 'short', ttl: 1000, limit: 10 },     // 10 req/sec
      { name: 'medium', ttl: 60_000, limit: 100 }, // 100 req/min
      { name: 'long', ttl: 3_600_000, limit: 3000 }, // 3000 req/hr
    ]),
  ],
  providers: [
    { provide: APP_GUARD, useClass: ThrottlerGuard },
  ],
})
export class AppModule {}

Helmet adds a battery of HTTP security headers (Content-Security-Policy, X-Frame-Options, Strict-Transport-Security, and so on). Wire it up in main.ts:

import helmet from 'helmet';
// inside bootstrap()
app.use(helmet());

Pitfall #4: If you serve Swagger UI in production, the default Helmet CSP rejects inline scripts and styles, which breaks the docs. Either disable Swagger in production with a NODE_ENV check (recommended) or relax CSP for the /api route with a path-scoped middleware. Do not weaken the global CSP just to keep the docs visible.

Step 13: Package and Deploy with Docker

The final step is shipping the application. NestJS produces a plain Node.js application, so any container runtime, PaaS, or serverless platform works. The pattern below is a multi-stage Docker build that yields a ~180 MB production image and a sub-second cold start.

# Dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate
RUN npm run build
RUN npm prune --production

FROM node:22-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/prisma ./prisma
COPY --from=build /app/package.json ./
EXPOSE 3000
USER node
CMD ["node", "dist/main.js"]

Build and run:

docker build -t nest-store-api .
docker run -p 3000:3000 
  -e DATABASE_URL='postgresql://...' 
  -e JWT_SECRET='...' 
  nest-store-api

# Image size: 179 MB
# Cold start: 720 ms (Node.js 22, Apple M2 Pro)

For Kubernetes deployments, add a readiness probe at /health using the @nestjs/terminus package, which ships first-class healthcheck building blocks for HTTP, the database, memory, and disk.

Five Common NestJS Pitfalls and How to Avoid Them

Across hundreds of NestJS code reviews, the same five categories of mistake show up over and over. Internalize this list before you ship.

Pitfall #5: Forgetting to enable the global ValidationPipe. Without it, every DTO decorator is dead code and your controllers happily accept malformed input. The fix is one line in main.ts, and the omission is the single most common bug in NestJS pull requests.

Pitfall #6: Returning Prisma models directly from controllers. Prisma’s Decimal type serializes to a JSON string (“129.99”), not a number. Either map to a response DTO with class-transformer or use Prisma’s $extends to convert Decimal to number at the client boundary.

Pitfall #7: Mixing imperative res.send() with NestJS controller return values. NestJS expects you to return a value or throw an exception. If you inject @Res() and call res.send() yourself, you bypass the interceptor pipeline and the global response shape. Use @Res({ passthrough: true }) if you absolutely need raw response access.

Pitfall #8: Overusing @Global(). It is convenient, but it makes module boundaries fuzzy and turns the dependency graph into spaghetti. Use it only for cross-cutting services like Prisma, Config, and Logger; never for feature modules.

Pitfall #9: Ignoring the Express v5 migration. NestJS 11 ships Express v5 as the default. Wildcard routes (app.use('*', ...)) and the req.query parser have changed semantics. If you upgraded from NestJS 10, run your full e2e suite and grep your code for the strings '*' and query.; you will probably find at least one regression.

Troubleshooting: Eight Recipes for the Most Common Errors

The following recipes cover the eight errors most likely to bite you between nest new and your first production deployment. Save the page; you will come back to it.

Symptom	Likely cause	Fix
Nest can't resolve dependencies of the X (?)	A provider is referenced from a module that does not import its declaring module, or the declaring module does not export the provider.	Add the provider to the exports array of its module, then add the module to the imports array of the consuming module.
Cannot find module '@prisma/client'	Prisma client was not generated after a prisma migrate.	Run npx prisma generate and commit the regenerated client.
UnauthorizedException on every request after JWT setup	The JWT_SECRET on the issuer differs from the validator, or the token expired.	Confirm both JwtModule.register and JwtStrategy read JWT_SECRET from ConfigService, not from process.env directly.
400 Bad Request with empty body	Global ValidationPipe with forbidNonWhitelisted rejects unknown properties.	Either remove the offending property from the request or relax the option for that specific DTO.
Swagger UI is blank in production	Helmet CSP blocks inline scripts.	Disable Swagger in production, or scope a relaxed CSP to /api only.
Prisma Decimal serialized as string	Default JSON serialization preserves precision.	Map to a response DTO with @Transform(({ value }) => Number(value)) from class-transformer.
Slow startup time on Apple Silicon	Native bcrypt binary not built for arm64.	npm rebuild bcrypt --build-from-source or switch to bcryptjs.
Memory leak under load	Forgotten subscription in an Observable returned from an interceptor.	Use the RxJS takeUntil pattern or convert to async/await for one-shot calls.

Advanced: Caching with Redis, Microservices, and GraphQL

Once you have a stable REST surface, three NestJS features deserve a deeper look: caching, microservices, and GraphQL. Each is a one-package addition that you do not have to commit to up front.

Cache Manager with Redis

NestJS ships @nestjs/cache-manager, a thin wrapper around the popular cache-manager library. Pair it with cache-manager-ioredis-yet for a production cache. The @CacheKey() and @CacheTTL() decorators let you cache responses at the controller level, and the CacheInterceptor attaches automatically once the module is imported. Typical results: read endpoints drop from ~12ms to ~0.5ms once the cache is warm, and your PostgreSQL load drops by 70 to 90 percent on hot products.

Microservices Transport Layer

NestJS exposes a built-in microservices API with first-party transports for TCP, Redis, NATS, MQTT, gRPC, RabbitMQ, and Kafka. The v11 release line includes ongoing transport improvements, and the v12 roadmap mentions a NATS v3 migration. The same controller and service code that powers your REST API can be exposed over message brokers with the @MessagePattern decorator. This is the path you take when you outgrow a single HTTP service and need event-driven communication between teams.

GraphQL with Apollo or Mercurius

The @nestjs/graphql package supports both Apollo Server 4 and Mercurius (Fastify). Pick code-first with TypeScript decorators (@ObjectType, @Field, @Resolver) for new schemas; pick schema-first if you already have a .graphql file you need to honor. The integration is so clean that many teams run REST and GraphQL side by side from the same NestJS process.

Performance Benchmarks: NestJS 11 on Express v5 vs Fastify 5

The most common question on NestJS threads is “how slow is NestJS, really?” The honest answer is that the framework overhead is between 8 and 15 percent compared to the bare adapter. Tech Insider’s own French-language NestJS 11 benchmark, run in April 2026, clocked the framework at roughly 12,000 requests per second on a representative REST workload — about 2.4 times faster than an equivalent Next.js API route. To switch from Express to Fastify, you change one line of main.ts from NestFactory.create(AppModule) to NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter()), and your throughput roughly doubles for trivial JSON endpoints. The table below shows the order-of-magnitude difference for a synthetic GET /ping endpoint on an Apple M2 Pro running Node.js 22.

Configuration	Requests per second	p95 latency	Memory at idle
Express v5 (raw)	~38,000	3.1 ms	52 MB
NestJS 11 on Express v5	~33,000	3.5 ms	78 MB
Fastify 5 (raw)	~78,000	1.6 ms	49 MB
NestJS 11 on Fastify 5	~68,000	1.8 ms	74 MB

The takeaway: NestJS adds about 4 to 13 percent of overhead, and that overhead is identical whether you sit on Express or Fastify. If raw throughput matters, switch to Fastify. If you are doing real work (database queries, external API calls), the adapter choice is invisible compared to your I/O budget.

Complete Working Project: nest-store-api Layout

The final project includes 14 files totaling roughly 850 lines of TypeScript. The structure looks like this:

nest-store-api/
+-- prisma/
|   +-- schema.prisma
|   +-- migrations/
+-- src/
|   +-- auth/
|   |   +-- auth.controller.ts
|   |   +-- auth.module.ts
|   |   +-- auth.service.ts
|   |   +-- jwt.strategy.ts
|   |   +-- jwt-auth.guard.ts
|   +-- common/
|   |   +-- filters/all-exceptions.filter.ts
|   |   +-- interceptors/logging.interceptor.ts
|   +-- prisma/
|   |   +-- prisma.module.ts
|   |   +-- prisma.service.ts
|   +-- products/
|   |   +-- dto/create-product.dto.ts
|   |   +-- dto/update-product.dto.ts
|   |   +-- products.controller.ts
|   |   +-- products.module.ts
|   |   +-- products.service.ts
|   +-- app.module.ts
|   +-- main.ts
+-- test/
|   +-- app.e2e-spec.ts
+-- Dockerfile
+-- .env.example
+-- package.json
+-- tsconfig.json

Run the full happy-path test suite at any point with npm test && npm run test:e2e. Both should be green within ~6 seconds on a modern laptop. If a test fails, the most likely culprit is a stale Prisma client; run npx prisma generate and try again. The second most likely culprit is a missing .env entry that Joi rejects at startup, which Jest surfaces as a confusing “ConfigService could not resolve” error.

Frequently Asked Questions

Is NestJS production-ready in 2026?

Yes. NestJS has been production-ready since at least version 6, and the v11 release line shipping in May 2026 is the most stable yet. Companies like Adidas, Roche, Capgemini, Decathlon, and Société Générale run NestJS at scale. The framework’s main risk is the same as any opinionated framework: if your team rejects the dependency-injection style, you will fight the framework instead of with it.

Should I use Express or Fastify as my NestJS adapter?

Use Express v5 (the default in NestJS 11) unless you have measured proof that the adapter is your bottleneck. Express has the largest middleware ecosystem and the most StackOverflow answers. Switch to Fastify only when raw JSON throughput dominates your workload, such as a high-RPS public API with minimal database work.

Should I use TypeORM or Prisma with NestJS?

For new projects in 2026, Prisma is the recommended choice. Its type safety is best-in-class, its migration tooling is excellent, and it has a thriving plugin ecosystem. TypeORM remains a reasonable choice if you already have a TypeORM codebase or if you need the Active Record pattern; for a tutorial-grade new project, Prisma is faster to get productive in.

How does NestJS compare to Spring Boot?

Architecturally they are sibling frameworks: modules, controllers, services, dependency injection, decorators (Java annotations), and a strong testing story. The difference is the runtime: NestJS runs on Node.js with TypeScript, while Spring Boot runs on the JVM with Java or Kotlin. For teams that already write TypeScript on the frontend, NestJS removes the language switch and lets the team move full-stack with minimal friction.

Does NestJS support ESM?

Partially in v11, fully as of v12.0.0, which launched in August 2026 with ESM-ready packages and Standard Schema support baked in, according to Tle Apps. NestJS 11 still defaults to CommonJS, which keeps Jest and most existing libraries happy, but teams that have already moved to the v12 line (now at v12.1.3 as of October 2026) get full ESM as the default. For projects starting before that upgrade, CommonJS remains the path of least resistance; ESM-first development is no longer a future conversation but the current default on v12.

Can I deploy NestJS to AWS Lambda or Cloudflare Workers?

Yes for AWS Lambda using @vendia/serverless-express or the official AWS Lambda adapter pattern; the cold start is acceptable (~600ms to ~1.2s) for moderate traffic. Cloudflare Workers is harder because NestJS depends on Node.js runtime features that Workers does not expose; if you need Workers, look at Hono instead and accept that you are giving up the NestJS dependency-injection model.

How long does it take to learn NestJS coming from Express?

A senior Express developer can build a real NestJS REST API in two to three days. The conceptual leap is dependency injection, modules, and decorators. The official docs at docs.nestjs.com are unusually high quality, and the CLI’s code generation handles 80 percent of the boilerplate. If you prefer structured coursework, the “NestJS Zero to Hero” course had drawn 107,351+ students and 7,921+ reviews on Shortcutsgpt as of May 2026, a sign of just how many teams are ramping up on the framework right now. After two weeks you will resent every legacy Express service you maintain.

Is there a reason not to use NestJS?

Three legitimate reasons. First, your team strongly prefers functional, dependency-light code; NestJS is the most class-heavy framework in the Node.js ecosystem. Second, you are deploying to an edge runtime that does not support full Node.js; pick Hono instead. Third, your project is small enough that the framework structure feels like overkill; for a 200-line internal tool, plain Express or Fastify is fine.

Related Coverage

For more on the ecosystem this tutorial sits inside, see our deep dives on Bun vs Node.js 2026, the Prisma ORM Tutorial, the Drizzle ORM Tutorial, the FastAPI REST API Tutorial, the GraphQL Apollo Server Tutorial, the Bun JavaScript REST API Tutorial, and the TypeScript vs JavaScript 2026 comparison. Our coding-tools cluster pillar at the AI Coding Tools Guide ties the broader landscape together.

Closing Thoughts: When NestJS Pays for Itself

NestJS is not the smallest framework on Node.js, not the fastest, and not the most fashionable. It is the most maintainable. Every NestJS codebase looks more or less like every other NestJS codebase, because the framework imposes module boundaries, dependency injection, and a deterministic request lifecycle. That uniformity is invisible in week one and decisive in month eighteen.

If you are building a SaaS backend that needs to survive five years of feature creep, twelve engineers cycling in and out, and a migration from monolith to microservices, NestJS in 2026 is the safest Node.js choice on the table. The 13-step path in this tutorial gives you the production-grade skeleton: modules, controllers, services, DTOs with validation, Prisma persistence, JWT authentication, OpenAPI documentation, exception filters, logging interceptors, rate limiting, Helmet headers, Jest tests, and a Docker deployment. From here, the framework gets out of your way and lets you build features.